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INTRODUCTION 



APL - THE LANGUAGE 

The Language APL and its acronym are derived from the mathematical language propound- 
ed by K. E. Iverson in a book entitled "A Programming Language" (John Wiley and Sons, 
Inc. 1962). 

The Language is essentially a large set of primitive, i. e. , predefined, functions for man- 
ipulating and performing computations on data. The notation used is very compact. A 
single APL character conveys the primitive function desired, and function expressions 
consist of an infix notation associating the arguments with the function being called. Prim- 
itive functions have one or two arguments- One argument appears to the right of the APL 
character conveying the desired function. If a second argument is required it appears to 
the left of this character. Arguments can themselves be function expressions. Evaluation 
of the expression proceeds from right to left. 

Unlike functions in other programming languages, most primitive functions in APL are 
defined for general arguments. While single valued arguments are possible as a special 
case, in general the arguments are array data structures and the functions operate in a 
predefined manner on these structures as a whole. 
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THE APL*STAR SYSTEM 

The implementation of APL on STAR computers is known as the APL*STAR system. 

The principal component of the system is a conversationally interactive interpreter design- 
ed for time sharing terminal operation. Upon gaining access to the system, APL expres- 
sions keyed on a terminal are evaluated and results, if requested, are displayed immediately. 

In addition to operating the system as a sophisticated desk calculator, the following features 
endow it with the capabilities of a complete programming system. 

• A procedure exists for a user to define his own APL functions in terms of APL 
expressions using previously defined or existing functions. 

• Extensive diagnostics, debugging aids and editing facilities exist to make the APL 
programmer extremely productive. 

• Methods exist whereby a variety of terminal types can gain access to the 
APL*STAR system and exchange data and programs. 
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SPECIAL NOTATION 

The following notation is not part of the APL language but rather is used in describing that 
language. 

-f ^- indicates the contents are optionally included. 

\_ j select one. 

.#♦ repeat as required. 

< > indicates a descriptive term rather than a literal APL construct. 

«--*. indicates identity, i. e. , that the expression on the left has the same 

value as the expression on the right. If used in the context of a constraint, 
the expressions must have the same value for the constraint to be satis- 
fied. 

;=; approximately equal 



Where examples are shown in this manual, a clear workspace (see ')CLEAR') is understood 
to exist prior to input of the first line, unless otherwise stated or implied by the example 
itself. 
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DATA 



ARRAYS 

All data in APL is handled in the form of arrays. An array is a finite set of data elements 
which in general are multiply- or ctered in a coordinated wa^ 7 ". 

COORDINATE 

Each coordinated ordering is termed a coordinate and is designated by a canonical ordinal 
for reference purposes. 

RANK 

The number of coordinates is called the rank of the array. 

LENGTH 

Each coordinate has an associated non negative integer called its length which is the number 
of different order positions used in that ordering. 

ORDER POSITIONS 

Order positions for a given coordinate are those constituting the set of the first L ordinals, 
(see ORDINALS), where L is the length of that coordinate. 

Each order position for each coordinate is assigned to an equal number of distinct elements, 
such that all elements have one such assignment. 

The assignment of order positions to elements by all coordinates is such that the canoni- 
cally ordered set of order positions for each element is unique. 

CANONICAL RAVEL 

The canonical ravel of an array is the single -ordered set of original array elements in 
canonical coordinate precedence sequence. 

SHAPE 

The shape of an array is the si«gle-ordered -set ef coordinate lengths in canonical order. 
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EMPTY 

An array is said to be empty if it has no elements. At least one of its coordinates has a 
length of zero. 

DATA TYPES 

Three data types are defined in APL*STAR: numeric, character and list. The value of a 
numeric data element is a single real number. The value of a character data element is a 
single character. The value of a list data element is the value of the array imbedded in 
the element (see IMBED). 

CHARACTERISTIC DATA TYPE 

All elements of an array in APL must be of the same data type, called the characteristic 
data type of the array. Even empty arrays have a characteristic data type. 

VALUE OF AN ARRAY 

The value of an array is the totality of its intrinsic attributes as characterized by its shape, 
canonical ravel and characteristic data type. 

RANK TERMINOLOGY 

An array of rank is called a scalar. It has no coordinates and exactly one data element. 
An array of rank 1 is called a vector. It has one coordinate and zero or more data elements. 

An array of rank 2 is called a matrix. It has 2 coordinates and zero or more data elements. 

An array of rank 3 or greater has no special name. It has as many coordinates as its rank 
and zero or more data elements. 

RANK LIMITATION 

The APL language does not define any limit to the rank of an array. However, the 
APL*STAR implementation will not allow the user to create arrays of rank greater than 127. 
Any attempt to exceed this limit will result in an error message (usually RANK ERROR). 

LiMiTATiON ON NUMBER OF ELEMENTS 

The APL language does not define any limit to the number of elements in an array. 
However, the APL*STAR implementation currently will not allow the user to create arrays 
having more than 65, 535 elements. An attempt to exceed this limit results in the error 
message NONCE ERROR. 
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ARRAY CREATION AND VARIABLES 



Arrays are created by the APL interpreter by evaluating APL expressions. An APL 
expression is a syntactic construct of APL language elements which together totally detail 
the construction of an array. 

Evaluation of an APL expression involves one of three processes within the interpreter, 
singly or in combination depending on the complexity of the APL expression. 

1. APL language elements exist from which literal expressions may be formed. 
These are interpreted directly and result in arrays having the value as stated 
in the expression. 

2. An expression may state a function to be called with designated arguments. The 
interpreter executes the function which in turn produces an array as its result. 

3. An expression may reference a currently defined variable. Such reference results 
in the interpreter making available an array having the value of the one being 
referenced. 

LITERAL EXPRESSIONS 

Literal expressions allow explicitly valued scalars and vectors to be directly expressed. 
LITERAL CHARACTER EXPRESSIONS 

A character scalar is expressed by placing the desired character in quote marks, thus: 
'A' 

A character vector is expressed by placing zero, two, or more characters within quote 
marks. 

'AB' a 2-element character vector 

'ABODE' a 5-element character vector 

i t a -element character vector 

To indicate that a character appearing within quote marks is the quote character itself, two 
consecutive quote marks are used to represent the single character. 

'DON' '?" a 5-element character vector DON'T 

»»''"»"" a character scalar T 
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LITERAL NUMERIC EXPRESSIONS 

A numeric scalar is expressed by formulating a numeral from the 13 APL characters 
0123456789. ~E 

• Unsigned integer and decimal numerals are formed in the usual manner. 

• A negative value is indicated with the negative symbol character "-" (read as 
'negative' or ^neg 1 ). 

• The character E is used to convey base 10 exponentiation and can be read 
'times 10 to the'. 

• The character e may be used in place of the character E. 

"6 

3.14159625 

4. 325E17 

2. 5937 6E~3 > exponent must be an integer 

10E"5 \ 

. 475 Note: embedded spaces 

47 o are not allowed. 

Numerals having any number of digits may be formed, but will only express the value 
represented by the 14 (in some cases 15) most significant digits. Proper scaling will 
always take place. 

Numerals expressing a value beyond the number representation capability of STAR com- 
puters will result in the error message SYNTAX ERROR. (See appendix C. ) 

A numeric vector is expressed by juxtaposing two or more numerals each separated by 
one or more space characters. 

2. 37 5493 "2.86E47 

1 -element vectors, 0-element numeric vectors and arrays of rank 2 or greater cannot be 
conveyed in a literal expression. Such structures can only be expressed by a call of a 
suitable function with appropriate arguments, or by referencing an existing variable having 
such a shape. 
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VARIABLE DEFINITION: SPECIFICATION 

The process of variable definition is called specification . The APL language syntax is: 
<identifier> « — <APL expression> 



In this process, a variable is created whose name is the identifier given, and whose value 

1 <3 fl-io ualno !""»•? tVio nnr>ov r» v» a «-. + a /A K-rr f V. r> A TDT ^-^v^™,-* ,*. „,' 

.„ „ ^*. „ XJ .^ i*j. j. cijr ^ j. v, o. i. -^ -~i >-rj uiv iij. J_; CAJJlCODiUUi 

Examples: 

COUNT+1 
The variable COUNT now has the value of the numeric scalar 1. 

TEXT*-' THIS IS IMPORTANT 1 
The variable TEXT now has the value of the character vector: 'THIS IS IMPORTANT' 
RULES FOR FORMING IDENTIFIERS 

• Names may be from one to 4095 characters in length. 

• The first character must be an alphabetic character (A to Z, a to z, A»& )• 

• The remaining characters (if any) may be any alphabetic character or digit, 
or the underscore character ( ). 

REFERENCING VARIABLES 

Whenever the identifier of a variable appears in an APL expression, it refers to that 
variable. On detecting the presence of a variable identifier, the APL interpreter makes 
available an array having the value of the variable being referenced. 

If the variable has not been defined, a reference to it results in a VALUE ERROR. 

A<-2. 3 ~57 3 4E3 
XA17a^-A 

In the first line above, A is specified as the variable identifier for the vector 2. 3 ~57. 3 
4E3 D The appearance of A in the second line refers to the variable stated above. The 
reference makes available a vector 2 3 ~57. 3 4E3 which is then associated with a data 
identifier XA17a. Two variables now exist having the same value, one identified by A, the 
other by XA17a. Subsequent occurrences of A or XAl7a in APL expressions refer to the 
corresponding variables. 
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RESPECIFICATION 

If a new value is given to the variable A by means of a subsequent specification, for example: 
A«-'NEW A' 

the previous value of A is no longer referenceable, and hence no longer exists. Note that 
there are no restrictions on the type or shape of the value newly specified to A. It need bear 
no relation as to type or shape of the previous value of A. A new specification for A in no 
way alters the specification for XAl7a. It still is associated with vector 2. 3 "57. 3 4E3. 
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DISPLAYING DATA 



SYNTAX 

The APL language provides a facility for displaying data. The language syntax for con- 
veying this process is: 

D^-<APL EXPRESSION> 

The character □ is called QUAD. If the left-most operation indicated in an APL source 
line is other than a specification, display of the evaluated APL expression is implicit, and 
the construct □< — need not be present in this case. 

D-f-2 + 2 2 + 2 

4 

DATA OBJECT DISPLAYS 

All data displays consist of a tabular arrangement of character representations of the 
elements of the array. For character data, each data element, being a character, is dis- 
played as that character (or by the mnemonic for that character where it cannot be formed 
on the terminal being used; see appendix B). 

Note that character arrays are displayed without enclosing quote marks: 

A 

'ABC 1 
ABC 



Note that single quote marks are displayed as such: 



i i i i 

t 

'DON* '2 71 
DON'T 



For numeric data, each data element is represented by a suitable format of characters 
which together convey the value of the numeric element. 



List arrays may not be displayed. An attempt to display a list array will result in a 
NONCE ERROR. 
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All displays begin at the left margin and element representations are displayed left to right 
in element order. Scalars are displayed in the same manner as a one-element vector. 

Each rank 1 subarray display occupies at least one display line. If the number of charac- 
ters required to display a complete rank 1 subarray exceeds WIDTH (see SYSTEM 
COMMANDS), its display will continue on subsequent lines with an appropriate indication of 
continuation (usually an indentation of 6 character positions). Each data element represent- 
ation will be complete on one line. 

Rank n-1 subarrays of rank n arrays are displayed in structure order. 

Between subarrays of rank 2 and higher a blank line is displayed. 

NUMERIC ELEMENT FORMATTING 

The amount of significance used in formatting numeric arrays is controlled by an environ- 
mental parameter known as DIGITS. The normal setting for this parameter in APL*STAR 
is 8. Numeric elements are formatted into one of two possible forms, decimal or 
exponential, depending on the value to be represented and on the setting of DIGITS. A 
rounded representation of the element value in the form of DIGITS digits is obtained, the 
left-most being non-zero unless the value is zero. Any value whose magnitude when round- 
ed as above is less than 10 and not less than 0.001 will always be expressed in decimal 
form regardless of the setting of DIGITS. 

Numeric Format Rules 

No more than DIGITS digits may be printed, unless they are leading zeros. 

• No more than three leading zeros may be printed. 

Decimal Form 

[~] <integral part> [,<fraction part>] 

• Magnitude scaling is indicated by insertion of a decimal point after the appropriate 
digit position. 

• If the magnitude of the element value is less than 1, the integral part is represented 
by a single zero. 

• Trailing zeros in the fraction part are suppressed. 

• If the fraction part is entirely zero, the decimal point is suppressed. 

• Negative values are indicated with a leading negative symbol character - . 
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Examples: 



1.235 



) DIGITS 4 



1.2348 



42.927 



42.93 



.123 



0.123 



7.0004 
7 

.0012365 
0.001237 

".0012365 
" . 1 2 3 7 



.00099997 



0.001 



Exponential Form 

In all cases where decimal form is unsuitable, exponential form is used. 

<coefficient> E <exponent> 

• The coefficient is formed from the DIGITS digits stated above for decimal form. 

m A decimal point is inserted to the right of the left-most digit. Coefficients thus 
always have a magnitude less than 10 and greater than or equal to one. 

m Suppression of trailing zeros and the decimal point, and use of the negative symbol 
are the same as for decimal form. 

m The exponent is an integer with appropriate value to indicate proper scaling of the 
coefficent as formatted, with a leading negative sign if the exponent is negative. 

Examples: 



) DIGITS 4 
8 

12348 
1 .2 3554 

"429273.8 
"4.293F5 



9999. 5 



1Z74 



19980800 A 



4-3 



NUMERIC DATA OBJECT FORMATTING 

All numeric data objects are formatted as if they were matrices. A vector is formatted as 
a matrix with one rank 1 subarray. A scalar is formatted identically to a one- element 
vector. An array B of rank greater than two is treated as a restructured matrix Bl formed 
as follows: 

Bl«-( (x/-l+pB),"l+ P B)pB 

Elements within each column of the above matrix are formatted uniformly as follows: 

• The same element representation form (decimal or exponential) is used. Unless 
one or more elements must be formatted in exponential form, either by the criteria 
stated in numeric element formatting or as a consequence of the following format- 
ting rules, decimal form will be used. 

• Decimal points are aligned (i. e. , occur in the same character position) for all 
element representations. This may entail appending one or more spaces to the left 
and one or more zeros (and decimal point) to the right of the fraction part as 
appropriate. If this causes a violation of the Numeric Format Rules stated above, 
exponential format is used for the column. 



DISPLAYING NUMERIC DATA OBJECTS 

Recall that all data objects consist of line displays of the rank 1 subsets in subset order, 
with element representations appearing left to right in element order beginning at the left 
margin. 

Since all elements within each column of the numeric matrix are uniformly formatted and 
aligned, all such element representations will appear in vertically aligned and uniformly 
formatted columns, appearing left to right in matrix column order, with two blanks between 
adjacent columns. 

Where displays are continued on indented lines, these should be visualized as additional 
columns that conceptually belong increasingly to the right of the display. See example on 
opposite page. 
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exampLe: 



)DIGITS 5 
8 

) WIDTH 60 

63 

J-*-. 275396 14.323 692738 12345 678 

X 
0.275396 14300 692738 12345 678 

) WIDTH 30 
60 

X 

0.275395 14300 692738 12345 

78 (display continuation indented) 

J-t-3 2p42 1.729 "173.52 6.83452~10 .9 
Y 
42.00 1.7000^009 
"173.52 6.83452~10 
0.90 0.00002000 
)DIGITS 4 
5 

7 
4.200201 1.7002009 
"1.7352C2 6.8352"10 
9.0002"! 0.0002000 
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COMPOSITE DATA OBJECT DISPLAYS 

Several evaluated expressions can be displayed in sequence in one composite display by 
arranging the expressions in desired display sequence and separating them with semicolons: 

<expression>; <expression>;. . . ; <expression> 

Each APL expression is evaluated starting with the right-most and proceeding to the left- 
most. 

If the display syntax Q<— occurs within the expression, the expression evaluated at that 
point is displayed immediately. 

After the left-most expression is evaluated, a composite display is output for all those 
expressions set up for display in reverse order to that in which evaluated; i. e. , in the 
left to right order in which the expressions appear on the line. 

For consecutive displays of scalars or vectors, output is displayed contiguously on the 
same output line. Displays of expressions of higher rank are displayed in a vertical 
format. Continuation lines are indicated in the same manner as for a single display. 

Both numeric and character expressions may be formatted in the same composite display. 
This feature provides the main use of composite displays. With this feature, result dis- 
plays can be annotated with character descriptions in the style of an edited report. 



Examples: 



QUANTITY** 
UNIT _RR I CE+1. 5 

'COST OF ' ; QUANTITY;' UNITS IS ' \QUANTIT7xUNIT_PRICE 
COST OF 3 UNITS IS 4.5 

5+|>i3; 'ZXC 1 ;B«-2 1 9 ;[>' XYZ ' ; 2 3pi6 
X?Z (first QUAD) 

12 3 /oo^An^ HTTAn\ 



(composite display) 
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PRIMITIVE FUNCTIONS 



The basis of the APL language is a large set of predefined functions. Because their 
designators are part of the language, they are terme^ primitive xuncions. 

NOTATION 

The notation used in describing the syntax of APL constructs is as follows: 

9 The right argument of a function is indicated by the meta-identifier "B". It is 

understood that any valid APL expression may be used in place of this meta-identi- 
fier. 

The left argument of a function (if one exists) is indicated by the meta-identifier "A" 
as for "B" above. 

If the function produces a result, that fact is indicated by the meta-construct "X*- ". 
It is understood that no actual specification of the result need take place. 

# The function itself and any associated APL characters required are indicated by the 
symbols in question. These symbols must be used as shown. 

9 Function Indices (see INDEXED FUNCTIONS) are indicated by the meta-identifier 
"K" enclosed in square brackets following the function to be indexed. Any valid APL 
expression may be substituted for "K". If "K" is elided, the square brackets must 
also be elided, "j" is used as a reverse index and follows the same rules. 

m If a syntax involves a general primitive function, this function is represented by the 
meta-symbol "f". Any valid APL primitive function may be substituted for "f", 
subject to the restrictions specified in the case in question. 

9 If a second general primitive function is used in the syntax, it is represented by the 
meta-symbol "g", as for "f". 

# Other syntactic constructs are indicated by a description of the construct enclosed 
in angular brackets (e. g. , < index list> ). It is understood that any syntactic con- 
struct following the rules specified in the case in question may be substituted for the 
meta-construct above. 

Exceptions to this notation are indicated where they occur. 
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Example: 

In this example, the function "(J)", modified by the function index "[K]", with right argument 
"B" and left argument "A", produces a result "R". Following this form, here is a possible 
usage of the above function: 

3<}>Cl]l 2 3 4- 
»+123 

Since the result was not specified after completion, it was displayed. 

SYNTAX 

Primitive functions are of two types: monadic (i. e. , having one argument), and dyadic 
(i. e. , having two arguments). The syntax for calling each type is: 

monadic: 

<special APL character><argument expression> 
dyadic: 

<argument expression><special APL character><argument expression> 

Most of the special APL characters used in designating monadic APL primitive functions 
are also used in designating some dyadic APL primitive function. In most cases, but not 
all, there is some similarity between the function procedure invoked in each case. The 
actual function called in each instance is, however, quite distinct. 

DOMAIN AND RANGE 

The class of arguments and the class of results of a given function are called its domain 
and range , respectively. 

The domain for character arguments and the range for a character result is the APL charac- 
ter set. 

The largest numeric class currently defined for APL*STAR is the set of real numbers 
for which an exact or approximate representation exists on STAR computers. Complex 
and other non-real number classes are not currently defined for any APL primitive 
functions. 
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Certain numeric arguments and results oi' function are confined to a subclass of the defined 
real numbers, namely the integers. Ordinals (see below) are members of this class. 

Other numeric arguments and results of functions are confined to a subclass of the integers 
consisting of the integers and 1. This subclass is known as the logical or Boolean class. 
(See Boolean numbers. ) 

tt„~w ~f fi-,^ f^wnrf^i^rt ^Iqocpc ic nlpnrlv a siihrlass of pach class nrecedinp" it. and anv 
function defined on a class clearly applies to any of its subclasses. 

Any argument supplied to a function which is not in its domain of definition or for which the 
result is not in the defined range of definition results in a DOMAIN ERROR message. 

ORDINALS 

Ordinal numbers are the numbers used to state position or ranking in an ordered set. The 
names of these positions are first, second, third, etc. 

It is customary to assign values to represent these positions identical to those used to 
represent the positive integers: 



First 


1 


Second 


2 


Third 


3 



It is sometimes more convenient to assign the values as follows: 

First 

Second 1 

Third 2 

Once the value for first has been decided upon, second is assigned the next higher integer 
value, and so on. 

The two schemes indicated are classified according to the value assigned for first, and are 
known respectively as ORIGIN 1 and ORIGIN 0. 

The scheme to be followed can be designated by using the system command )ORIGIN 
(see ORIGIN command). 

Various APL functions are defined which use ordinal arguments. Some others produce 
ordinal results. 

The domain of definition of such functions for such arguments is the positive integers for 
ORIGIN 1 and the positive integers and zero for ORIGIN 0. 



19980800 A 5-3 



BOOLEAN NUMBERS 

Boolean numbers are truth values and are usually defined for logical systems of two values 
as true and false. It is customary by convention, to represent the Boolean 'number' 
(i. e. , truth value) true by the number 1 and false by 0. 

This convention has been followed in the implementation of APL. The domain of definition 
of functions defined for such arguments and the range of those functions yielding such re- 
sults are the numbers 1 and 0. 

Such functions must be given arguments whose elements consist of the appropriate number 
of ones and zeros. 

It should be understood that the meaning of a 1 or is that of the truth value - true or false 
when it is the argument of a Boolean function, regardless of the fact that it may be the re- 
sult of some prior numeric computation. 

CONFORMABIUTY 

As stated in the introduction, a key feature of APL is the fact that the primitive functions 
are defined for general arguments; i.e., the arguments are arrays, usually of more than 
one element, and the functions operate in a predefined manner on the array structure as a 
whole. 

For most primitive functions there is some constraint placed on the generality of the argu- 
ments). Any rule which limits the generality of shape of an acceptable argument of a 
function is called a conformability rule , Conformability rules are classified as either sin- 
gular or dual. 

• Singular Conformability: A conformability rule for a monadic function or one which 
pertains to a specific argument of a dyadic function independent of any shape for the 
other argument is said to be singular. 

• Dual Conformability: A conformability rule for a dyadic function which states a 
relationship between the shapes of the two arguments is said to be dual. Certain 
dual conformability rules also implicity convey a singular conformability require- 
ment for one of the arguments. 

Conformability rules are stated as part of the description of each primitive function where 
one or more apply. 
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Violation of a conformability rule results in a RANK ERROR or LENGTH ERROR as approp- 
riate unless overriding rules are applicable. 

OVERRIDING CONFORMABILITY RULES 

Conformability rules are subject to the following overriding rules, whereby a conforma- 
bility rule may be relaxed or somewhat altered. 

The following rules have precedence in the order listed. 

1. A scalar is treated as a one-element vector where singular conformability 
requires a vector argument. This process is known as scalar extension. 

Exceptions: 

• A scalar cannot be indexed. 

• The left argument of DYADIC IOTA must be a vector. 

« The argument of GRADE UP and GRADE DOWN must be a vector. 

2. A one-element vector is treated as a scalar where singular conformability 
requires a scalar argument. 

3. Where a dual conformability rule exists, a scalar or one-element vector argument 
is treated for function execution as a restructured array having the minimum rank 
and number of elements required to meet all conformability requirements. This 
is another form of scalar extension. The restructured shape will not result in an 
empty data object unless that is specifically required. 

Exceptions: 

• The left argument of TAKE, DROP, and EXPAND 

• Both arguments of TRANSPOSE 

• Both arguments of MATRIX DIVIDE 

This rule, when applied to INDEXED SPECIFICATION (q.v. ), relates to the implied 
shape of the index list taken as a whole, and not to individual elements which make 
up the list. Note that this may result in an indexed expression with bad form if 
multiple specification to the same indexed element is implied. 



I 
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ORIGIN 

In an ordered set, specific members are designated by an integer called an ordinal spec- 
ifying the order position in the set. The ordinal of each member is one greater than the 
ordinal of its predecessor. The ORIGIN parameter is the value designated to the ordinal ■ 
of the first member of the set. APL-STAR allows the ORIGIN to be set to either or 1. 

The normal setting for ORIGIN in APL*STAR is 1. To change the setting of ORIGIN, see 
the system command )ORIGIN. 

The first element of the result returned by monadic IOTA (q. v. ) is ORIGIN. Thus the 
setting of ORIGIN may be found from 1 1 : 

il 

1 

) OR I Gill 

il 



Since the ORIGIN designates the value of the ordinal of the first member of any set, any 
function that uses ordinals as an argument or returns ordinals as a result is said to be 
origin dependent. 

Currently there are six primitive functions defined in APL that return ordinals as a result. 
These are: 

1. monadic iota \D 

2. dyadic iota Ai£ 

3. monadic query - ? # 

4. dyadic query A ?B 

5. grade up IB 

6. grade down V£ 

The primitive function dyadic transpose requires the left argument to be a vector of ordinals. 

dyadic transpose A$B 
All forms of indexing employ ordinals as indices. 

1. expression indexing A[B] 

2. indexed specification A[B] < — 

3. indexed primitive functions f [K]B and Af [K]B 
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SUBARRAY OPERATIONS - INDEXED FUNCTIONS 

Nearly all primitive functions in APL are defined for array arguments. In most cases, 
the basic operation is defined in terms of arrays of a specific structure, and extended to 
arrays of other structure by performing the operation in parallel on all basic subarrays of 
the array given. 

All scalar functions are defined in terms of scalars. For higher rank arrays, the opera- 
tion is carried out using corresponding scalar subarrays of the argument(s) (see SCALAR 
FUNCTIONS). 

Many non-scalar functions are defined in terms of vectors (catenation, reduction, compres- 
sion, etc. ). If the array given is of lower rank, it is extended, if possible, in a manner 
appropriate to the function in question. If the array is of higher rank, the operation is 
carried out using vector subarrays of the argument(s). 

In this case, however, the choice of the elements which constitute each subarray is non- 
trivial. For a rank N array, there are N possible coordinate axes along which the vector 
can be chosen. 

In order to resolve this question, a Function Index is used. This takes the form of an index 
expression, enclosed in square brackets, following the function in question: 

R<- f[K]B 
or R^Af[K]B 

The index expression must evaluate to a one -element vector ordinal, designating the 
coordinate axis along which the vector subarrays are to be chosen. From this it is 
apparent that for an index K, and an array of rank N, the domain of K is: 

Ke\N 

If an index is not specified for the function, it defaults to the ordinal of the last coordinate 
namely: 

The functions which may be so indexed are: 



/ 


Compress 


\ 


Expand 


f/ 


Reduction 


* 


Reverse, Rotate 


dyadic , 


Catenate, Laminate 



19980800 A 5-7 



REVERSE INDEXING 

All indexable functions as described above have an alternate designator which specifies 
reverse indexing. The corresponding alternate designators are: 

/ - / 

\ + \ 
it + f7 



If an index J is specified with a reverse index designator, the result obtained is equivalent 
to that obtained using the regular designator with an index ($\N)lJ] 

If no index is specified in this case, J defaults to "l+itf as did K so that the designated 
coordinate is 

i.e., the first coordinate. 
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RELATIVE FUZZ: USE IN RELATIONALS 

In the comparison of any two numeric data elements the following three relational cases 
are always mutually exclusive: 

A>B 

A = B A and B scalars 

A<B 

To consider A to be equal to B only when the internal representations of the argument are 
identical would be undesirable for the following reasons: 

9 Numbers in STAR series computers can only be represented with 14 significant 
digits of accuracy (15 digits for integers with a magnitude less than 2*47). 

# The deviation between the represented value and the exact value is proportional to 
the magnitude of the represented value. 

m If successive operations are applied to such data elements, the inherent error in 
such represented values will propagate to the result such that the relative deviation 
from the theoretical result could be several times the initial relative deviation. 

# Alternatively, the data initially supplied may be significant to much less than 14 
digits even though internally represented as such. 

For these reasons, it is usually desirable for numeric relational operations to be treated 
as follows: 

# Consider A equal to B if A lies anywhere in the inclusive range B± |B x factor. 

# If A is smaller than the lower limit of this range, consider A to be less than B. 
Otherwise consider A to be greater than B. 

This is exactly how numeric relational operations are performed in APL. The factor used 
is called FUZZ. The range B x FUZZ is termed the relative FUZZ. Note that the range of 
the relative FUZZ is proportional to the magnitude of B. Thus, the relative FUZZ for a B 
of zero is zero. 

The following primitive functions also perform comparisons between data elements in the 
same manner as the relationals: 



with numeric arguments 

However, k and^do not use FUZZ. 

The normal setting for FUZZ in APL*STAR is 
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USE OF FUZZ IN RELATIONALS 



A>B 
(A-B+\B*FU7,Z)>0 



& 



RELATIVE FUZZ 
BxFUZZ 



A=B 

((A-B+\BxFUZZ)Z0)*iA-B-\BxFUZZ)2t0 
I 

A IS IN THE INCLUSIVE RANGE B+\BxFUZZ 



RELATIVE FUZZ 



A<B 
(A-B-\B*FUZZ)<0 



Nl/ 



NOTE: A>B++(A>B)vA=B 

A<B++(A<B)vA=B 



B+\BxFUZZ 



B-\B*FUZZ 
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ABSOLUTE FUZZ 

The following primitive functions use FUZZ itself (ABSOLUTE FUZZ) in determining their 
results. 

FLOOR 

Conceptually, FLOOR is a monadic function which returns the largest integer less than or 
equal to its argument. 

In fact, FLOOR adds the value of FUZZ to the argument and then takes the conceptual 
FLOOR of that. 

The conceptual FLOOR is the behaviour of FLOOR with FUZZ set to zero. Let L represent 
the conceptual FLOOR. Then: 

CEILING 

In a similar manner, ceiling operates as follows: 

INTEGER DOMAIN 

Many APL primitive functions require integer arguments (Boolean and ordinal domains are 
subsets of the integer domain). 

The test for acceptability as integer is: 
((!"#)-LB) = 

If the above relationship is true, B is accepted as the integer LB. If the accepted integer is 
a member of the required domain no domain error report is issued. 

Regardless of the setting of FUZZ all result values defined to be in integer domain will be 
represented exactly if their magnitude is less than 2*47. 

GENERAL NOTES 

Note that for functions employing ABSOLUTE FUZZ, the fuzzing is of uniform width for all 
argument values and is based solely on the setting of FUZZ. 

Also note that for such functions' no acceptable setting of FUZZ has any effect on arguments 
greater than or equal to 2*47. 
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USE OF ABSOLUTE FUZZ 



FOR THIS DESCRIPTION FUZZ-0. 125 



FLOOR 
R+-LB 



-» 



FUZZ 
FUZZ 



R*-2 






i?«-l 



-it 



fl+0 



R+ 1 



CEILING 
R+[B 



R+3 



Rf-2 



X 



R+l 



R+0 



3.125 
■2.875 

2.125 
1.875 

1.125 
0.875 

0.125 
'0.125 



INTEGER 
IFTFCFR DOMA li 17 *--*- ( ( [ B ) - L B ) = 
R+( xl0)[£] 



FUZZ 
FUZZ 



DOMAIN ERROR 




DOMAIN ERROR 



&- 



R+l 
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SEED 

The functions ROLL and DEAL (q, v, ) Generate pseudo-random integers. Each element so 
produced is generated from an environmental parameter known as SEED. The algorithm 
used is such that a given combination of SEED and range (supplied by the argument(s)) pro- 
duces a unique, predictable result element. However, the process of producing the element 
alters the value of SEED, so that the distribution of many elements produced sequentially 
is pseudo-random and flat. 

Likewise, successive uses of these functions produce results which, while in fact com- 
pletely determined, appear random and independent. Thus, "random" test sets may be 
reproduced by setting SEED to the same value prior to each test. To set this parameter, 
see ")SEED". 
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SELECTION PRIMITIVE FUNCTIONS 



A SELECTION FUNCTION is one in which the result consists solely of elements supplied 
from the argument(s), and fill elements. 

t^„ _+„;„ qP ioM^n nnpratinns. Roecificallv TAKE and EXPAND, Fill elements are re- 
quired to create an array of the required shape from the argument given. For numeric 
arrays the fill element is zero, and for character arrays the fill element is the space 
(blank) character. For list arrays, the fill element is a zero length list vector. 

All selection functions are capable of operating on arrays of any data type, and produce a 
result of the same data type 

For dyadic selection functions other than CATENATE (q.v. ), one argument (usually the 
right) is used to supply the array from which elements are to be selected, and the other to 
control the particular selection being performed. Unless otherwise specified, the domain 
of these control arguments is integer . 

In general, restrictions on data type mentioned above or in the definition of the individual 
selection functions do not apply if the argument in question is empty . 
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DYADIC RHO: RESHAPE 



syntax: 

domain: 

c o nf or m ab il ity : 



result shape: 
definition: 



identity: 



R+ApB 

/1>0 and integer; A may be type character if empty. 

(pp4)=l 

(p4)<127 (APL*STAR limitation) 

= x/A if 0=x/pB 

If B is a vector, and the number of elements in the array indicated 
by dimensions A is exactly the number of elements of B, then the 
result is an array of shape A such that: 

( ,R)++B 

If the result requires N elements, and there are more than N 
elements in B, only the first N are used. 

If there are insufficient elements in B to fill the array indicated by 
A, the elements are chosen cyclically from B until the array R is 
filled. This process is known as Cyclic Replication . 

If B is not a vector, then: 

i?«--*i4p ,B 

( s £)<-+(x/pB) P B 

Note: If A is empty and B is a list array, the result 
is not defined. 



examples: 






X+2 3 8 1 4 7 
6pX 


2 


3 


8 


14 7 
2 3pJ 


2 


3 


8 






ti 


n 


2 3 lpZ 


2 








3 








8 








1 








4 








7 
9 






lpX 



IpX 
2 3 8 14 7 2 

2 4pJ 
2 3 8 1 
4 7 2 3 

r\ _ v 

(blank) 

( \0)pX 
2 

2pi0 
DOMAIN ERROR 
$: 2pi0 



(result is empty) 
(result is a scalar) 



(A must be empty if 
B is empty) 
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MONADIC RHO: SHAPE 



syntax: 
result shape: 

definition: 

note 1: 

note 2: 



J?«-pB 

The result is a vector with N elements, where N is the number of 
dimensions in the array B. 

The jth element of R is the length of the jth coordinate of B (see 
ARRAYS). 

Although Shape is not a selection function, it is included here 
because it is integral to the discussion of selection functions. 

The rank of an array is found by applying the Shape function twice. 
RANKB*-ppB 



examples: 



(blank) 
(blank) 



P 5 

pM 



p3 7.9 3.2 
PMBZ7 37 1 



(a scalar has an empty shape) 



(the shape of a vector is 
the number of elements) 









1 
1 

2 3 

2 7 9 



p lO 
P" 

Pp7 
ppM» 

pp4 7.2 5 3 ~8 
ppMBCZ? 1 

p2 3pl 7 9 2 3 6 
p2 7 Sp'XYZ 1 



(an empty vector has a 
shape of zero) 



(the rank of a scalar is zero) 



(the rank of a vector is one) 



(shape of higher rank arrays 
( see RESHAPE)) 
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MONADIC COMMA: RAVEL 



syntax: 
result shape: 

definition: 

examples: 



The result is a vector of N elements, where N is the number of 
elements in B. 

The result consists of the elements of B, selected from it in row 
major order. For further discussion, see ARRAYS. 



5 
5 

1 i+ 7 
14 7 



X 

a 

Y 
,Y 

z 



13 2 
7 8 4 

.2 
13 2 7 8 4 

W 
1 3 
7 8 



2 5 
9 4 



.V 



13782594 
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INDEXING 



syntax: 



R*-BL< index list>] 

The form of the index list for a B of rank N is 

I I * I 2* • • • » I N 

where each J T is an expression of any rank, or may be elided. 
N-l semicolons must appear. 



domain: 
conformability: 

result shape: 

definition: 



I j ordinal 



(ppB)=ff 
(ppB)>l 



(number of indices) 

(may not be circumvented by scalar extension of B) 



Let PT+fnT \.Cnr 1.. r\T 

Then (pi?)=i?I unless RI is empty and B is a list array (see below). 

The result is formed from elements selected from B as designated 
by the index list. The index list also governs the shape of the result 
and the position each selected element will occupy in the result. 
Each expression in the index list evaluates to an array of ordinals 
called the index for the corresponding coordinate. Each ordinal 
specifies a position of that coordinate. If no such position exists, an 
INDEX ERROR results. 

Index expressions may be elided. In this case the index expression 
defaults to 

that is, a vector of all position ordinals of coordinate J in position 
order. 

An element is selected for every combination of coordinate ordinals. 
The position of each selected element in the result is determined as 
follows. 

The first element of the canonical ravel of the result is that element 
of B having coordinate positions as indicated by the first ordinal 
in every canonically raveled index. This is followed by those 
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elements of B in which only the last coordinate position is changed 
to that of successive ordinals of the ravel of the last index. This 
is followed in like manner by those elements of B having coordinate 
positions corresponding to index ordinal combinations obtained by 
using succeeding elements from each index in turn until all 
combinations are exhausted. 

The shapes of the indices do not affect element selection but 
compositely dictate the shape of the result. 

Note that since the index elements are ordinals, the selection 
process and hence the result is ORIGIN dependent. (See ORIGIN). 

If B is a list array, and RI is empty (i. e. , a scalar is indexed from 
B), then R is the value of the array which was imbedded in the 
selected element of B. This is the inverse operation to that of the 
IMBED function (q.v. ). 



identity: B++ ( cB ) [ ? 1 ] 



7 
8 3 



J-*-4 3 7 5 8 
JC3] 

I[S 2] 

XL 2 3pl 3 2 4 2 5] 



4 7 3 

5 3 8 

XC6] 
INDEX ERROR 
$: X[6] 

JCiO] 
(blank) 

X+2 3p1 3 7 5 8 1 

X 

4 3 7 

5 8 1 

Xlll 
RANK ERROR 

$: XL11 

ALi;i] 
4 

*[2;1 2] 
5 8 

XL 2 1;3 2 3 1] 
18 15 
7 3 7 4 
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3 8 

3 
8 



*C;2] 
XC;,2] 

) OR I GIN 

I[0:0] 





B«-2 3 4p\24 




£[1;2;1 2] 


5 6 






5[1;;]C2;] 


5 6 


7 8 




B[,l;;][l;2 3;1][2] 


9 






L-*-cMBC" 




LCI] 


ABC 






LC1H1 3] 


AC 






pp(l+OpL)[?l] 


1 






pp(l + Op M» )C?1] 








(indexing twice) 
(indexing 3 times) 



(create list - see IMBED) 
(Scalar indexing reveals 
imbedded element) 



(test for L type list) 
1 if list 
if not list 
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INDEXED SPECIFICATION 

syntax: R +Xl < index list > 1+ B 

The underlined portion of the syntax represents the indexed 
specification proper, while the remainder of the syntax is required 
for consistency with the definition of other primitive functions. 
X is the name of a variable. 
The form of the index list for an X of rank N is 

I l iI 2 ; "' iI N 

where each I. is an expression of any rank, or may be elided. N-l 
semicolons must appear. B is the result of the most, recent 
expression evaluation on the same line and must exist. 

conformability: (ppX)=N (number of indices) 

(ppZ)^l (may not be circumvented by scalar extension) 

Let i?l^(pl 1 ),(pl 2 ) pI N 

Then (( l*pB)/pB )«--►( 1*RI)/RI 

Unless RI is empty and X is a list array (see below). 



domain: 



definition: 



B must be a of the same type as X unless RI is empty and X is a 
list array (see below). 

I j ordinal 

Indexed specification like ordinary specification is not a primitive 
function but a directive. The operation requires and uses the 
result value of the most recent expression evaluation on the same 
line but leaves that result undisturbed and available as the right 
argument to some subsequent function whose designator appears 
further to the left in the source line. Such a result may also be 
used by successively left occurring directives, all of which leave 
the result undisturbed. 

Indexed specification assigns the value of each element of B to an 
element of the variable X as designated by the index list. Any 
element of X not so designated retains its current value. 
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examples: 



Rules pertaining to the index list are the same as for INDEXING. 
In addition the following rules apply: 

1. The additional conformability rule stated above. 

2. The index list has bad form and the operation is not defined if 
multiple elements of B are specified to the same position in X 
i.e. required is a/i=+/( , J )o . = t j 

3. X must be an existing defined variable. 

If X is a list array and RI is empty, (i.e., a scalar element of X 
is indexed), B is imbedded in the selected element of X. 

As with indexing the operation is ORIGIN dependent. 



X+l 2 3 

*[2>5 

X 
15 3 

X[l 2>5 4 

X 
5 4 3 

Xll 2>1 

X (scalar extension of B occurs) 

113 

I-^XLl 2>1 

j (result is B, not X) 

1 

X*-2 3pl 2 3 4 5 6 

X 
12 3 
4 5 6 

X[;2>9 8 

X 
19 3 
4 8 6 

X[2]-«-9 8 
RANK ERROR 

$: ZC2 3+-9 8 

X[;4>9 8 
INDEX ERROR 

$: X[;4>9 8 

) ORIGIN 
1 

X 
19 3 
4 8 6 

X[;2>4 5 
1 X 

19 4 
4 8 5 



19980800 A 6 " 9 



M+3 1 4pil2 
M[i2;l;i3>l 2 3 lpO 
M 
00 4 

8 

9 10 11 12 

X+* 5pcMBC" (create list variable - see IMBED) 

J[2;3>3 4pxl2 (imbed into X [ 1;3] ) 

J[l;4] (reveal X[l;4]) 

ABC 

X[2;3] (reveal X[2;3]) 

12 3 4 
5 6 7 8 
9 10 11 12 

pX 
4 5 

JC2;3Kl;3 
15 9 
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DYADIC COMMA: CATENATE 



syntax: 



domain: 



R+A,LK1B 
R+A?U1B 



(reverse indexed) 



Three cases exist: 



conformability: 



result shape: 
definition: 



A and B must be of the same data type. K follows the rules for 
TT,,nr.tinn TnHir.es (see INDEXED FUNCTIONS). K is integer. 



• (pp4)=ppB 

• (ppA)=l+ppB 

In this case, B is treated as Bl obtained from: 
Bl+(((K*\ppA)\pB)+K=\ppA)pB 

• (l+pp4)=pp5 

This case is the mirror image of the above case. A is treated as 
Al obtained from: 

Al+(((K*\ppB)\pA)+K=\ppB)pA 

In the discussion below, the first case only is considered. 
Behavior of the other two extend from the first via the above rules. 

(( K* i p pA )/ pA )«-•*■( K* \ p p B ) /p B 

(ppA)Zl 

(p.pB)*l 

(pR)<r+(pB) + (K=\ppB)\(pA)lKl 

If A and B are vectors of length M and N respectively, then the 
result R contains M+N elements, the first M of which are the 
elements of A, and last N are the elements of B. 

If A and B are arrays of rank 2, vector subarrays are selected 
along the Kth coordinate axis, and catenated as above to form vec- 
tors along the Kth coordinate of the result. 

Since K is an index, the result, if K is not elided, is ORIGIN 
dependent. 

If r is used, Reverse Indexing applies. 
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examples: 



2 3 4 



2 3,4 5 

5 

X+-2 3pl 2 

J«-2 3p7 8 

X 



3 4 5 6 

9 10 11 12 



7 8 9 
10 11 12 



X.I 

7 8 9 
10 11 12 
X t llini;l 



X,IUI 

3 

6 

9 



10 11 12 

X- t I 

12 3 

4 5 6 

7 8 9 



(first coordinate used) 



10 11 12 



X,101I 
INDEX ERROR 

$: X,[0]Y 
) ORIGIN 
1 

X.lOlI 

12 3 

4 5 6 

7 8 9 

10 11 12 

X- t Y 

12 3 

4 5 6 

7 8 9 

10 11 12 

12 3 7 8 9 
4 5610 1112 

X,I 
12 3 7 8 9 
4 5 6 10 11 12 



) OR I GIN 1 


X t 12 13 
1 2 3 12 
4 5 6 13 

J,C1]12 13 
LENGTH ERROR 

$x X,Llll2 13 

X,[l]12 13 14 
12 3 
4 5 6 
12 13 14 

J, 5 
12 3 5 
4 5 6 5 

Z+2 2 2p 12345678 

PpZ 
3 

Z,l 2 
RANK ERROR 

$: Z,l 2 
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DYADIC COMMA: LAMINATE 



syntax: 



domain: 



conf or inability: 
result shape: 

definition: 



R+A, LKlB 



(reverse indexed) 



A and B must be of the same data type. K follows the rules for 
Function Indices (see INDEXED FUNCTIONS). 



JV(<j>il + pp£)[rX]-l| \K 



K is not integer 

( n A W-»-n R 

N*-+/K>\ppB 
(pR)<~+(N+pB) t 2 t N+pB 

A result is created with a dimension of 2 inserted after the Nth 
dimension of B. A is placed in the first position on this new 
coordinate axis, and B is placed in the second position: 

Rl+(NipB) ,l,#+pB 

R+(RlpA),l[KlRlpB 
Since K is an index, the result, if K is not elided, is ORIGIN 
dependent. 

If -; is used, Reverse Indexing applies. 



1 2 3, [.534 5 6 
12 3 
4 5 6 

1 2 3, [1.534 5 6 

1 4 

2 5 

3 6 

1 2 3, [2. 534 5 6 
INDEX ERROR 

I: 1 2 3, [2. 534 5 6 
(2 3p6+i6),[.532 3pi6 
7 8 9 
10 11 12 

12 3 
4 5 6 



(2 3p6+i6) 
7 8 9 
4 5 (6 

10 11 12 
4 5 6 

) ORIGIN 
i 

1 2 3 , [ ~ . 2 ] 4 5 6 
12 3 
4 5 6 

1 2 3 T [ .434 5 6 

1 4 

2 5 

3 6 



19980800 B 



6-13 



TAKE 



syntax: 
conformability: 



R+A+B 
(pA)<-+ppB 



This may not be circumvented by 
scalar extension of A unless (pp5) = l 



result shape: (pf?)+U (see ABSOLUTE VALUE) 

definition: Two cases exist: 



• (U[J])<(pB)[I] 

• ( UCJ])>(p5)[J] 
"ORDINARY" TAKE 



("ordinary" take) 
("too much" take) 



If B is a vector, and AtO the result is the first A elements of B. 
If A<0 , the result is the last \A elements of B. 

If B is a scalar, A must be empty, and the result is B 

If B is an array of rank £2, and AlIl^O, the result is formed by 
selecting the first A III positions along coordinate axis I. If 
Alll<0, the last UC J] positions are selected. 

"TOO MUCH" TAKE 

If Alllzo, the elements of B occupy the first Ai I] positions along 
coordinate I of the result. If i4[J]<0, the last UC J] positions 
are used. 

When the selection is complete, fill elements are placed in any 
unoccupied positons of the result. 

Take is not ORIGIN dependent. 

(See examples on next page. ) 
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examples: 

3+1 2 3 4 5 

1 2 3 

3+1 2 3 4 5 
3 4 5 

X+3 4pil2 

X 
12 3 4 

C C 7 D 

9 10 11 12 

2 3 + X 
12 3 

5 6 7 

"2 "3+J 
6 7 8 

10 11 12 

2 ~3+X 

2 3 4 

6 7 8 

5 + 1 2 3 
12 3 

f Z?' ,~4+MSC" 
Z? 4BC 

4 "5+Z 
12 3 4 
5 6 7 8 
9 10 11 12 


2 3 + 5 
5 (scalar extension) 



S-H>(x0)+7 
7 

ppS 
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DROP 



syntax: R+-A+B 

eonformability: (pA)-ppB 



This may not be circumvented by 
scalar extension of A unless (ppZ?) = l 



result shape: (pR)++(pB)-\A 

definition: Two cases exist: 

• (UCI])i(pB)Cl3 

• (UCJ])>(pB)[J] 

In this case, A is treated as if it were AI obtained from: 
Al-«-(xA)x(pB)L \A (see signum, minimum) 

If B is a vector, and 4^0 , the result is all but the first A elements 
of B. If A<0 , the result is all but the last \A elements. 

If B is a scalar, A must be empty, and the result is B 

If B is an array of rank z2 , and A[I]ZQ, the result is formed by 
selecting all but the first A [I] positions along coordinate axis I of B. 
If j4[I]<0, all but the last|4[j] positions are selected. 



Drop is not ORIGIN dependent. 



(See examples on next page. ) 
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examples: 

2+1 2 3 4 5 
3 4 5 

~2+l 2 3 4 5 
12 3 

X+3 4pxl2 

X 
12 3 4 

I- /* f» e\ 

3 D / O 

9 10 11 12 

"1 + X 
12 3 4 
5 6 7 8 

5 + 1 2 3 
(blank) (result is empty) 

5 + X 
LENGTH ERROR 
$: 5+X 

Y«-5 1 + J 

7 
(blank) (Y is empty) 

P* 

3 

y-H>(xo) + 7 

7 

PPT 
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COMPRESS 

syntax: 

domain: 
conformability: 



result shape: 



definition: 



R+A/ZK1B 
R+AJUlB 
A must be Boolean. 

(ppA)=l 
(ppB)*l 
(piD-^-(pB)CX] 

(pi?)C!3= (pB)CJ] for I*£ 
+ /A for I=£ 

If B is a vector, the result is formed by selecting Bl J] if i4[I] = l, 
or ignoring it if^[J]=0. 

If B is an array of rank £2, the result is formed by using vector 
subarrays of B along the Kth coordinate axis. 

Since K is an index, the result, if K is specified, is ORIGIN depend- 
ent. If / is used, Reverse Indexing applies. 

(See examples on next page. ) 
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examples: 



1 3 



AC 



12 3 



10 1/12 3 
1 1/MSC 1 
111/12 3 
0/1 2 3 



(blank) 



(result is empty) 



1/1 2 3 
12 3 

0/1 2 3 

(blank) 

X+Z 4pil2 

X 
12 3 4 
5 6 7 8 
9 10 11 12 

10 1 0/X 
1 3 
5 7 
9 11 

1 1/LllX 
12 3 4 
9 10 11 12 

1 UX 
1 2 3 4 
9 10 11 12 

) ORIGIN 
1 

1 1/J 
12 3 4 
9 10 11 12 

1 1/[1]Z 
LENGTH ERROR 

$: 1 1/C1]J 

1 1 1/M» 

1 1/[1]X 
12 3 4 
9 10 11 12 



(scalar extension of A) 
(scalar extension of A) 



((pX)LU is now 4, not 3) 
(scalar extension of B) 
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EXPAND 

syntax: 



domain: 
conform ability: 



result shape: 



definition: 



R+AMKlB 
R+A\M1B 

A must be Boolean. 

(ppA)=l 
(ppB)*l 
(pB)lKl=+/A 

(pi?)CJ]= [(pB)tll for I*K 
I pA for i=k 

The result is formed rom B by extending the length of coordinate 
K to p-4 and inserting subarrays of fill elements into the 
positions along coordinate K corresponding to the positions of 
zeros in A. 

In addition, if (pB)lK]=l and A contains more than one 1, 
replication of the existing subarray will occur in ail succeeding 
positions along coordinate K corresponding to the positions of ones 
in A. 

Since K is an index, the result, if K is specified, is ORIGIN 
dependent. 

If VCeH is used, Reverse Indexing applies, 
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examples: 



1 1\1 2 

10 2 

10 1 1\MBC" 

A BC 

1 1\1 2 

1 2 

1 0\1 2 

LENGTH ERROR 

$: 1 0\1 2 



(B should have only 1 element) 



l u i\z 



2 2 



(scalar extension of B) 



X+2 3pi6 
X 

12 3 
4 5 6 

1 1 1\X 
10 2 3 
4 5 6 

i o lum 

12 3 

4 5 6 

1 1\Z 
12 3 

4 5 6 



) ORIGIN 
1 

1 1\X 
12 3 

4 5 6 

1 lUllX 
LENGTH ERROR 

$: 1 1\C1]J 



((pX)Cl] is now 3, not 2) 









1 


1 1\3 


lp4 


9 


7 


4 





4 


4 










9 





9 


9 










7 





7 


7 
















1 


1\[2]2 1 


3p- 


16 




1 


2 


3 












1 


2 


3 












4 


5 


6 












4 


5 


6 
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MONADIC ROTATE: REVERSAL 



syntax: 

conformability: 
result shape: 
definition: 



identity: 
examples: 



R+QtKlB 

/?"*-©[ J" ]B 

(ppB)*l 

If B is a vector, the result is formed by selecting the elements of 
B in reverse order. 

If B is an array of rank ">2, the result is formed by reversing 
vectors selected along the Kth coordinate axis of B. 

Since K is an index, the result if the index is specified is ORIGIN 
dependent. If ©CeT] is used, Reverse Indexing is implied. 

(4>lKlHKlB)<-+B 



3 2 1 



3 2 1 
6 5 4 



4 5 6 
12 3 



4 5 6 
12 3 



4 5 6 

12 3 

3 2 1 

6 5 4 

3 2 1 

6 5 4 



'12 3 



X+2 3pi6 
<$>X 



<Ki]* 

9X 

) OR I GIN 
9X 

<H13X 
©Co]* 
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DYADIC ROTATE 

syntax: 

conformability: 

result shape: 
definition: 



R+A&U1B 

(ppB)*l 
(pA)++(K*\ppB)/pB 

(pR)++pB 

If B is a vector, and AtQ, the result is formed by cyclically rota- 
ting the elements of B, A positions to the left: 

N+{pB)\A 
R+(N+B) t N+B 
If 4<0 S the elements are cyclically rotated to the right: 
27«--(pB)l \A 
R+(N+B),N+B 

If B is an array of rank £2, the vectors to be rotated are selected 
along the Kth coordinate axis of B. 

Each element of A specifies the rotation to be applied to the cor- 
responding selected vector subarray of B. 

Since K is an index, the result if the index is specified is ORIGIN 
dependent. If © is used, Reverse Indexing applies. 



identity: 



((-A)4>tKU<btKlB)<-+B 
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examples: 



24>1 2 3 4 5 

3 4 5.12 

~2<t>l 2 3 4 5 

4 5 12 3 

54»1 2 3 4 5 
12 3 4 5 



DAN 



'l$*AND 



X+3 4pil2 

X 
12 3 4 
5 6 7 8 

9 10 11 12 

1 2§X 
12 3 4 
6 7 8 5 
11 12 9 10 

1$X 
2 3 4 1 
6 7 8 5 

10 11 12 9 



6 7 8 

10 11 12 

2 3 4 
lQX 

6 7 8 

10 11 12 

2 3 4 



(scalar extension of A) 



) OR I GIN 



19 X 

5 6 7 8 
9 10 11 12 
12 3 4 



) ORIGIN 1 


m>[l]* 
5 6 7 8 
9 10 11 12 

12 3 4 

X+2 3 4pi24 

X 
12 3 4 
5 6 7 8 
9 10 11 12 

13 14 15 16 
17 18 19 20 
21 22 23 24 







P+2 3p 






P 


"2 


"1 





1 


2 


3 
P(j»Z 


3 


4 


1 2 


8 


5 


6 7 


9 


10 


11 12 


14 


15 


16 13 


19 


20 


17 18 


24 


21 


22 23 



10 12 3 
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MONADIC TRANSPOSE, DYADIC TRANSPOSE 

dyadic syntax: R+A§B 

monadic syntax: R+§B 

(in this case, the left argument defaults to A+$\ppB ) 

domain: AexppB 

conformability: (oA)-QpB 

(this may not be overridden by scalar extension of A or B. ) 
Case 1: A has no repeated elements. 

result shape: (p/?)<-KpB )UA] 

The transpose operation simply reorders the coordinate axis of 
the argument as indicated by the left argument. 

A useful rule-of- thumb for doing transpose operations is as follows: 
Write down the elements of pB; below it write the elements of A; 
on a third line, place the elements of pB in the position indicated 
by A. This line is then pi?. 

Example: For the operation 

3 1 2$4 5 6pil20 




5 6 ^4 
The shape of the result is 5 6 4. 

The effect of reordering the coordinates maybe seen as follows: 

B-*-2 3pi6 

B 
12 3 
4 5 6 

R+$B 

The elided left argument defaults to 2 1, so the shape of the result 
is 3 2. 
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The first coordinate has become the last, and the last has become 
the first. Thus, in the display the "rows" appear to have become 
"columns", and vice-versa. 



1 4 

2 5 

3 6 



Case 2 : A has repeated elements, 

domain: AeAxA (see DYADIC IOTA) 

result shape: (pi?) [I] = L /(A=I)/pB for all IexppR 

(ppi?) = i[i] + r/4 (see REDUCTION) 

In the previous case, the transpose reordered the argument coor- 
dinate axes. Now, they are not only reordered but some of them 
are combined into a smaller set of new coordinate axes (as indicated 
by the rule-of -thumb given for Case 1). 

The Ith coordinate axis of the result is formed from the coordinate 
axis(>l=J)/ipAof the argument array B. The resulting axis is the 
major diagonal of the axis from which it was formed. Only the 
elements along this axis are chosen for the result. The number of 
element positions along this axis is necessarily equal to the length 
of the shortest of the axes from which it was formed, i. e. , 
L/(t>B)Z(A=I)/\pAl 

Since the left argument consists of coordinate axis indices, the re- 
sult, if A is specified, is ORIGIN dependent. 

For example, consider the operation 

R+2 1 1$4 5 6pil20 

Using the rule -of -thumb: 







2 \ 1} 1 




choose f 5 4 




5 4 


The shape of the result 


ls 5 4. 



6-26 19980800 A 



The effect of combining coordinates may be seen as follows, 
Consider: 

B+3 3pi9 
R+l 1$B 

The result is selected from the diagonal: 

if 
15 9 

B 
12 3 
4 5 6 
7 8 9 



identities: 



(§§B)++B 
For case 1 - 

If B is of rank < 1: 

(A$B)+-*-B where A in this case must be ippB 



• 12 3 



12 3 







X+2 


2p MBCP' 






X 




AB 








CD 




§X 




AC 








BD 












X+2 


3 4pi24 






X 




1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 






1 3 


2§X 


1 


5 


9 




2 


6 


10 




3 


7 


11 




4 


8 


1.2 




13 


17 


21 




14 


18 


22 




15 


19 


23 




16 


20 


24 





(A defaults to 1) 
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§X 




1 13 






5 17 






9 21 






2 14 






6 18 






10 22 






3 15 






7 19 






11 23 






4 16 






8 20 






12 24 








1 2 


2§X 


1 6 


11 




13 18 


23 






2 3 


3$* 


DOMAIN ERROE 


$ 


?: 2 


3 3$J 




) ORIGIN 


1 








1 2 


2$X 


DOMAIN ERROR 


$: 1 


2 2$X 




1 


1$J 


1 6 


11 




13 18 


23 




1 5 


9 




2 6 


10 




3 7 


11 




4 8 


12 




13 17 


21 




14 18 


22 




15 19 


23 




16 20 


24 






(i0)$7 


7 







(A defaults to 3 2 1) 



(A\A is 1 2 3) 



(A\A is 1 1) 
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SCALAR PRIMITIVE FUNCTIONS 



GENERAL 

The class of functions whose primary definition is in terms of operation on one or two 



SCALAR MONADIC functions are defined in terms of a single scalar, while SCALAR 
DYADIC functions are defined in terms of a pair of scalars. 

For all scalar functions, the following rules hold: 

monadic syntax: Z?-«-fg 



dyadic syntax: 

domain: 

range: 



conformability: 
result shape: 



R+AfB 

A and B must be numeric (unless otherwise specified). 

R is numeric (unless otherwise specified). 

If R is outside the range of real numbers representable on the 
machine, a DOMAIN ERROR results. For APL*STAR, this 
range is ~9. 54E8644 to 9. 54E8644 (approximately). 



(pi4H-KpB) 
(pf?)<-+pB 

(p /?)«-► pB if (ppB)>ppA 
pA if (pp5)<ppi4 



for scalar dyadic s 
for scalar monadic s. 

for scalar dyadics 



MONADIC DEFINITION 

The result is formed by applying the function to each element of B, and placing the result- 
ing element in the corresponding position in R. 

DYADIC DEFINITION 

The result is formed by applying the function to each element of B and the element in the 
corresponding position in A, and placing the resulting element in the corresponding 
position in R. 
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SCALAR MONADIC FUNCTIONS 



MONADIC PLUS: IDENTITY 



syntax: 

definition: 

examples: 



R++B 
The result is the value of the argument. 



+ 23 



23 



+ -'1.5 2.7 1.1E~Z 
1.5 2.7 0.0017 



MONADIC MINUS: NEGATION 



syntax: 

definition: 

examples: 



R-*—B 

The result is the negated value of the argument. 

-23 



23 



-"1.5 2.7 1.7£~3 
1.5 "2.7 "0.0017 

MONADIC MULTIPLY: SIGNUM 



syntax: 
definition: 

examples: 



R+xB 



The result is 1, or 1 depending on whether the argument is 
negative, zero or positive. 



*23 



x 1.5 2.7 1E~3 

' 1 t * r\ 
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MONADIC DIVIDE: RECIPROCAL 

+ R+-*B 

syntax: 

domain: B"0 

definition: The result is the reciprocal of the argument. 



examples: 



t5 

0.2 

*"10 . 5E3 
"0.1 0.002 

*0 
DOMAIN ERROR 
$i i0 



MONADIC POWER: EXPONENTIAL 

syntax: R-*-*B 

definition: The result is the exponential of (e to the power of) the argument, 

e is approximated by 2. 718281828459045, 

examples: #1 

2.718281828 

*1. 5 
4.48168907 1 

*1E8 
DOMAIN ERROR 

$: *1E8 (result outside machine range) 
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MONADIC LOGARITHM: NATURAL LOG 

syntax: ]?•*-• B 

domain: B>0 



The natural logarithm function is the inverse of the exponential 
function. 



examples: 



A 


• *1 


1 


• 1 









• "1 


DOMAIN ERROR 




$: •"! 



MONADIC MINIMUM: FLOOR 

syntax: R+IB 

definition: The result is the greatest integer less than or equal to the argument. 

The result of this function is dependent on the setting of FUZZ. 

examples: Ll.5 

1 

L"1.5 3 "5 "4.1 "4.9 5.1 5.9 

"2 3 "5 ~5 ~5 5 5 

Ll-0.1 IE' 15 
i (second element within FUZZ of 1) 
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MONADIC MAXIMUM: CEILING 

syntax: R+[B 



definition: 



examples: 



The result is the smallest integer greater than or equal to the 
argument. The result of this function is dependent on the setting 
of FUZZ. 



Tl.5 



T~5 3 "5 "4.1 "4.9 5.1 5.9 
"5 3 "5 "4 "4 6 6 
MONADIC MODULUS: ABSOLUTE VALUE 



syntax: 

defintion: 

examples: 



The result is the absolute value of the argument. 

|"1.5 
1.5 



|"3 15 



3 15 
MONADIC CIRCLE: PI TIMES 



syntax: 
definition: 

examples: 



R+oB 

The result is Tftimes the value of the argument. ' r f is represented 
as approximately 3.14159265358979. 



oi 
3.141592654 

075.3*180 
1.314232927 



(number of radians in 75. 3 degrees) 
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FACTORIAL 

syntax: 

domain: 

definition: 



E+IB 

If B < 0, B must not be integer. 

The result is obtained from applying the Gamma function to the 
elements of B as follows: 

R+GAMMA B+l 
Note that if B is a non-negative integer, the result is that of the 

classical factorial function. 
!3 



MONADIC QUERY: ROLL 

syntax: 

domain: 

definition: 



examples: 



!0 1 2 3 4 
1 1 2 6 24 

!"0.5 3.7 10 
1.772453851 15.4314116 3628800 



R+?B 

B must be a positive integer. 



The result is an integer pseudo-randomly selected from integers 
\B, The roll function result is dependent on the settings of SEED 
and ORIGIN. 

?5 



?5 5 5 5 5 5 5 

3 14 2 15 4 

?1 
1 

) ORIGIN 
1 

?1 




(the setting of ORIGIN) 
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MONADIC TILDE: NOT 

syntax: 
domain: 
range: 
definition: 

examples: 



R+~B 

B must be Boolean. 

R is Boolean* 

The result is a 1 if the argument is zero, otherwise the result is 
zero. 



~1 1 1 
10 1 

-0.5 
DOMAIN ERROR 

$i ~0.5 



(argument not Boolean) 
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SCALAR DYADIC FUNCTIONS 

DYADIC PLUS: ADDITION 



syntax: 


R+A+B 


definition: 


The result is A plus B. 


examples: 


2 + 3 




5 




1 2 + ~l 5 




7 




"2+6 7 4.5 




M- 5 2.5 


DYADIC MINUS: 


SUBTRACTION 


syntax: 


R+A-B 


definition: 


The result is A minus B. 


examples: 


2-3 




"1 




1 15 12-10 




"9 5 2 



(scalar extension of A) 



(scalar extension of B) 
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DYADIC MULTIPLY 

definition: 
examples: 



The result is A times B. 
2x3 



1 10 100x1 2 3 
i 20 300 

. lFeoooxi^eooo 

DOMAIN ERROR 

$: i£60ooxi#6ooo 



(result outside machine range) 



DYADIC DIVIDE 

syntax: 
domain: 
definition: 
examples: 



R+A*B 

5*0 

The result is A divided by B. 

2*3 
0.666666667 

2 3 4*4 3 2 
0.5 1 2 

0*0 
DOMAIN ERROR 

$i 0*0 



(B must be non-zero) 
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DYADIC MODULUS: RESIDUE 



syntax: 
definition: 



examples: 



R-A\B 

R+B-A*LB*A+A=0 

Note that this function does not use FUZZ. The FLOOR and 
EQUALS operations in the definition are performed with 
FUZZ=0. (See ABSOLUTE FUZZ). 

10 | 15.3 
5.3 

1112.34 10 1.5 
0.34 0.5 

3]"4 "3 "2 "1 1 2 3 4 
201201201 

0)"4 "3 "2 "1 1 2 3 4 
"4 "3 "2 "1 1 2 3 4 

~3|"4 "3 "2 "1 1 2 3 4 
"1 "2 "1 "2 "1 ~2 

"14.3 "2.7 5.4 3.2|"6.1 47 "3.8 11.6 
"6.1 "1.6 1.6 2 
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DYADIC POWER 



domain: 



R+A*B 

In APL*STAR, if A is negative, B must be integer. 
If A = then 3>0 



ii H<yj uien jd is iinegcj 



definition: 



The result is A raised to the power B. Note that if A is negative 
and B is not an integer, the result is not real, and a DOMAIN 
ERROR results. 



examples: 



2*3 



10*"1 12 
"0.1 1 "10 100 

0.01 2 4 9*0.5 
0.1 1.4142136 2 3 

0.001 1 8 27**3 
0.1 1 2 3 

"1*0.5 
DOMAIN ERROR 

$: "1*0.5 
0*0 
DOMAIN ERROR 
$i 0*0 



(square root of A) 



(cube root of A) 



(if A is negative, B must be integer) 
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DYADIC LOGARITHM 



syntax: 


R+A9B 


domain: 


4>0,4*1 




B>0 


definition: 


The result is the logarith 


identity: 


B+A*AQB 


examples: 


2®3 




1.584962501 




10*0.1 1 10 1E2 




"10 12 




10®*1 




0.4342944819 




0»0 




DOMAIN ERROR 




$: 0©0 




1®1 




■ DOMAIN ERROR 




$i 1®1 



(common log of e) 



(A and B must be positive) 



(A must not be 1) 
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examples: 



DYADIC MINIMUM 

syntax: Rt-A'lB 

definition: The result is the smaller of A and B, 

2L3 
2 

1 3 5L~2 7 4- 
~ 2 3 U 

0L~1 '1 2 
"10 



DYADIC MAXIMUM 

syntax: R-*-A[B 

definition: The result is the Larger of A and B. 

examples: 2T3 

3 

1 3 5T~2 7 4 
17 5 

0T"3.5 1 5.2 
1 5.2 
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DYADIC CIRCLE 

syntax: 

domain: 

definition: 



R+AOB 

A must be integer, A^l t A^ 7 

The result is the trigonometric function of B indicated by A. The 
"normal" trigonometric functions are assigned to positive values 
of A, while their "inverse" is designated by the corresponding 
negative value of A. 

The domain of the "inverse" functions is usually the range of the 
"normal" function. The possible values of A and their correspond 
ing functions are listed below, along with their range and domain. 



A 


Function 


Domain 


Range 


A 


Function 


Domain 


Range 





(1-B*2)*0.5 


"1 thru 1 


thru 1 










1 


sin B 




"1 thru 1 


~1 


arc sin B 


-1 thru 1 


-TT ,, Tf 

T thru T 


2 


cos B 




"1 thru 1 


~2 


arc cos B 


"1 thru 1 


thru ff 


3 


tan B 


(00.5)*(01)|B 




-3 


arc tan B 




-tr , TT 
2 thru 2 


4 


(1+B*2)*0.5 




1 thruoo 


~4 


(~1+B*2)*0. 


,.p*thru "I 
D (i thru- 


thru oo 


5 


sinh B 






~5 


arc sinh B 






6 


cosh B 




1 thru«> 


"6 


arc cosh B 


1 thru«o 


thru*. 


7 


tanh B 




~1 thru 1 


"7 


arc tanh B 


"*1 thru 1 




Note: 


The domain of sin, cos 


and tan and the range of 







arcsin arcos and arctan are expressed in radian measure. 



examples: 



203 
"0.9899924966 

1 2 300 0.25 0.5 0.75 
0.7071067812 "l 

~502.3 
1.570278543 

3OO0.5 
DOMAIN ERROR 

$: 3oo0 . 5 



(cosine of 3 radians) 



(sin J , cos J, tan 3 J) 



(inverse hyperbolic sine of B) 



(tan 2 i s infinite) 
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EQUAL, NOT EQUAL 

syntax: 

domain: 

range: 

definition: 



examples: 



2 = 3 



ti-*-A-o ^equai; 

R*-A*B (not equal) 

No restriction. 

R is Boolean. 

Equal the result is one if A is equal to B, otherwise the result 
is zero. If A and B are numeric, the result is FUZZ dependent. 

Not equal R+~A=B 



2*3 



110 



M + l' = M + 4 f 



2 = M ' 



1 



M + l**'4 + + f 



2*M ! 



Oil 



3.5 1=1 1 



1=1+1£ 15 



3.5 1*1 1 



0*1£ 15 
1 

10 1*0 110 
11 



10 0- 



(A is within relative FUZZ of B) 



(relative FUZZ of zero is zero) 



(exclusive OR of A and B) 
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OTHER RELATIONALS 



syntax: 



range: 
definition: 



examples: 



R+A<B 
R+AzB 
R+AZB 
R+A>B 
R is Boolean. 



(less than) 
(less than or equal) 
(greater than or equal) 
(greater than) 



Less than - the result is 1 if A is less than B, otherwise it is 0. 

Greater than - the result is 1 if A is greater than B, otherwise it 
is 0. 

Greater than or equal - R+~A<B 

Less than or equal - R+~A>B 

The results of these functions are FUZZ dependent. 



2<3 2 

1 

2>3 2 


2<M» 

DOMAIN ERROR 
$: 2<M« 
2£3 2 

1 

2£3 2 

1 1 



(A and B must be numeric) 
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BOOLEAN FUNCTIONS 



syntax: 



domain: 

range: 

definition: 



examples: 



R+AkB 
R+AvB 

R«rA*B 

R-*-A*B 



(and) 
(or) 
(Nand) 
(Nor) 



R is Boolean. 

And - the result is 1 if both A and B are 1, otherwise it is 0, 
Or - the result is 1 if either A or B is 1, otherwise it is 0. 

Nand -R<r~A*B 
Nor - J?+~AvB 



1 



1 1 



1 







1A0 1 



lvo 1 



1*0 1 



1*0 1 
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COMBINATION 



syntax: 

domain: 

definition: 



examples: 



R+AIB 

If B is a negative integer, then A must be an integer. 

The result is obtained by applying the factorial function to the 
arguments as follows: 

R+(IB)*(IA)*IB-A ' " 

For AZO and B^A , the result may be expressed in terms of the 
Beta function: 

R+(B-A)*(A+1) BETA B-A 

If A and B are integers, the result is the number of combinations 
which can be made from B things taken A at a time. In this case, 
if A > B , the result can be seen to be zero. 



10 



2!5 
1!5 
0!5 
5!5 
7!5 
7*0 



2.517.3 
32.617667 

"2.515 
0.0036180411 

"2!5 


4.516*5 
0.00017356873 



2! 5 
"7!~3 

'3.5!~2.5 




15 

1 

"2.5 

3. 5! "5 

DOMAIN ERROR 

$: ~3.5!~5 



(A must be integer 
if B negative integer) 



j4-t-4- "7.5 ~4 ~4.5 
B«-5 5 "2.5 "2.5 ~5 

AlB 
5 ~4.1785964tf"5 4.375 1 



5! 2 

4 . 4 ! ~6 . 5 

7.5!~5 
DOMAIN ERROR 

$: 7.5!"5 

(A must be integer 
if B negative integer) 
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In addition to element-by- element application, three additional general procedures are 
defined for applying scalar dyadic functions to general array arguments. 

They are: OUTER PRODUCT, REDUCTION and INNER PRODUCT. 

A syntactic form exists which designates the desired procedure and the specific scalar 
dyadic function(s) to be employed in the procedure. 

Each procedure can be considered a composite function in which the domain and (with 
some exceptions as noted) the range is that implied by the scalar dyadic functions 
designated. 
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OUTER PRODUCT 

syntax: 

con for inability: 
result shape: 
definition: 



examples: 



R+A o . f B 

where f is a scalar dyadic primitive function. 

((pp>U+ppB)<127 (APL*STAR restriction) 

(pi?)«-(p/l),p2? 

If A is a scalar, the result is: 

R+A f B 

For A of rank ^1 , the result is formed by performing the above op- 
eration for each element (i. e. , scalar subarray) in A, and placing 
the resulting array in the subarray position of R corresponding to the 
position of the element in A. 



3 4 5 

2 3 4 

3 4 5 



2o.+l 2 3 



1 2o .+1 2 3 



2 10o.*~l 12 3 



0.5 12 4 8 

0.1 1 10 100 1000 

X<-2 3 pl00xi6 

X 
100 200 300 
400 500 600 

1+2 3pi6 

7 

12 3 
4 5 6 
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pZ 
2 3 2 3 

Z 

101 102 103 

104 105 106 

201 202 203 

204 205 206 

301 302 303 

304 305 306 



401 402 403 
404 405 406 

501 502 503 
504 505 506 

601 602 603 
604 605 606 
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REDUCTION 

syntax: 



conformability: 
result shape: 
definition: 



R+f/LKlB 
R+ftUlB 
where f is a scalar dyadic primitive function. 

The index [K] follows the rules for Indexed Functions. 

(pp£)>l 

(pfl)«-+(~(ippB)etf)/p3 

If B is a vector, the result R is a scalar formed from the 
distributed operation of the function f on the elements of B as 
follows: 

R+Blll f B[2] f .. . f B[pB] 
If B is a one element vector the result is: 



R+Blll 



(a scalar) 



If B is an empty vector and the function f has an identity element I, 
then 



R+I 



(a scalar) 



If B is an empty vector and the function f has no identity element, 
then a DOMAIN ERROR results. 

For B of rank greater than I, the operation is performed on vector 
s'ub arrays of B as indicated by the index K. Since K is an index, 
the result, if an index is specified, is ORIGIN dependent. If f/ is 
used, reverse indexing applies. 
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IDENTITY ELEMENTS 



Function 


Identity Element 


+ 





- 





X 


1 


* 


1 


r 


=:~9.54£8644 


L 


~9.5^E86im- 


! 






o 



Foi non-cuinuiutative fuactiuiis, an identity element, if it exists, 
may be only a left or right identity. The scalar functions and their 
respective identity elements are given in the table below: 

Comments 



right identity 

right identity 

smallest representable number 

largest representable number 

left identity 
1 right identity 

no identity 

no identity 
1 left identity 

1 Boolean only 

Boolean only 

Boolean right identity 

Boolean left identity 

1 Boolean right identity 
1 Boolean left identity 

1 



- no identity 

- no identity 
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examples: 



+ /1 4 3 
-/I »+ 3 



13 4 
6 2 5 



8 13 



7 5 9 



X«-2 3pl 3 1 6 2 5 
X 



+ /X 



+/L11X 



) ORIGIN 



8 13 



7 5 9 







2 3 



+/C1DX 



+ M 



t/3 Opl 



x/pl 



(addition identity elements) 



x/X 

SYNTAX ERROR 
$i \/X 

L/'/i 1 
DOMAIN ERROR 
$x L/ ! 4' 

®/[2]4 7 3p9 
DOMAIN ERROR 

St ®/[2]4 7 3p9 



( • has no identity element) 
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+ /T3 15 
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NNER PRODUCT 



syntax: 



conformability: 



R+A f . g B 

where f and g are scalar dyadic primitive functions. 

(pp4)>l 

(pp5)>l 

( (pp4)+pp5)<129 (APL-'STAR restriction) 

(~l + pi4 )=l + pB via extension if l=~l + p4 or l = l + pB 



result shape: (pi?)«--*-( ~1\qA ) , l + p S 

definition: If A and B are vectors, the result is obtained from: 

R+f/A g B 

If either A or B is of rank £2, the operation is carried out using 
vector subarrays of the argument, in question. Subarrays from A 
are selected along the last coordinate axis, and subarrays of B are 
selected along the first coordinate axis. 

Furthermore, for each vector subarray in A, the operation is car- 
ried out for all subarrays in B, in a fashion similar to Outer Prod- 
uct (q. v. ). 

If the length of the last coordinate of A or the first coordinate of B 
is one, scalar extension along that coordinate shall occur such as 
to make the two coordinate lengths the same. 

Recall REDUCTION: Note that if A and/or B are empty 
but 0*x/~l + pA and 0*x/i + pB the result will 

be non empty, consisting of function f identity elements as 
required for the resulting shape. If function f has no identity 
element a DOMAIN ERROR results. 
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ACLillpl-fcO. X ^ Ot.^lU X U.J. 

12.3 

;>2 3pi6 

Y«-3 2pl0 4 1 5 0.1 5 

X 
12 3 
4 5 6 

7 

10 .0 4 
1.0 5 
0.1 6 

X+.xY 
12.3 32 
45.6 77 

PX«-3 7 1 
J£«-4 2 7 
PJr.+.YC, 



A'-«-o 0.25 
tf«-10 

0.7071067812 

(1 1 lpl)+.x2 3p\6 (extended conformability) 
5 7 9 (result shape 113) 
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(3 Ipi3)+.x3 lplO 15 20 
<+5 
90 
135 

(1 3pi3)+.xl 3pl0 15 20 
60 90 120 

(2 Op iO)+.xO 3p lO 



(2 OpiO)=.>l 3p5 
111 
111 

(4 lplO)©.*0 2 3p7 
DOM All] ERROR 

$: (4 lpl0)®.*0 2 3p7 (« has no identity element) 
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MISCELLANEOUS PRIMITIVE FUNCTIONS 



MONADIC IOTA: INTERVAL 



syntax: 


R+\B 


domain: 


B must be integer. 




B^O 


eonformability: 


(ppB)=0 


result shape: 


{pR)++,B 


definition: 


The result is a vector of the first B ordinals. 


examples: 


i5 
1 2 3 4 5 

il 
1 (the setting of ORIGIN) 




i 

(the result is empty) 




p iO 


) ORIGIN C 
1 

\5 
1 2 3 M- 

il 


iO 




p iO 


tl 2 

LENGTH ERROR 

$ : ll 2 (B must be a scalar) 
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DYADIC IOTA: INDEX OF 

syntax: R+-A\B 

domain: A and B may be independently numeric or character. 

range: Ordinal. 

conformability: (p pi4 )-<--»• 1 

(Note: this requirement cannot be overridden by scalar extension. ) 

result shape: (pfl)-«-»-pB 

definition: The result has the shape of B. For each element of B, the corres- 

ponding result is the lowest index of A which selects a match for 
that element in A, if one exists. If no matching A element exists, 
the result element is assigned the value {pA ) + 1 1 (i. e. , one greater 
than the highest valid index for A). 

* Since the elements of the result are indices, the result is ORIGIN 
dependent (see ORIGIN). 

» If no element of A matches any element of B, for A not empty: 

J?«--*-(pF)p(p/.) + il 

If A is empty, /,■«-( pB)pil 

9 For A and B both numeric, element comparisons are subject to 
the setting of FUZZ (see FUZZ). 

m If sf t BeA then p-i-MCr?] 

(See examples on next page. ) 
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exa mp le s : )ORI GIL 



2 1 5 7 1 5 

3 

'ABCD' i *B' 
2 

2 15 7i6 
5 

'ABCD 1 i 'F ! 
5 

4 7 9i2 7 4 3 

4 2 14 

'WXYZ'xl 2 3 

5 5 5 

7 i 3 

. $: 7i3 (left argument must be a vector) 

( ,7)i3 
2 

( i0)i3 5 1 

111 

1 3 5 7 3 i 3 3pi9 
16 2 
6 3 6 
4 6 5 

p2 1 9x lO 
(recall (pR)-*->pB ) 
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DYADIC EPSILON: MEMBERSHIP 



syntax: 

domain: 

range: 



R+AeB 

A and B may be independently numeric or character. 
Boolean. 



conformability: None, 
result shape: ( p ^)^.^ p/ j 



definition: 



note: 



examples: 



The result has the shape of A. For each element of A, the corre- 
sponding result element is a one if that element of A exists in B; 
otherwise it is a zero. 

For A and B both numeric, element comparisons are subject to the 
setting of FUZZ (see FUZZ). 



2ci7 
1 

Be i 7 


A+2 9 7 3 4 

B«-6 12 4 

AeB 
10 1 

BeA 
11 

2 3et0 








1 2 3eMZW?2' 



p( i0)el 2 7 



1 XAYQ3B7' e M£C3» 
i 1 1 

MZ?C3»e 'XAY03B7* 
110 1 

(2 3p i6)e2 6 9 
10 
1 
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DYADIC QUERY: DEAL 



syntax: 

domain: 

range: 

conformability: 

result shape: 

definition: 

note: 



examples: 



R+A ?B 

A and B both integer: a>q , B^A 

Ordinal. 

(0=pp4)A0=ppB 

( n V \ J — *. A 
\ H ■" / ~ ' »■"■ 

The result R is a vector of A elements of \B selected pseudo- 
randomly without replacement, thus preventing duplicates. 

• Since the elements of the result are selected from X B , the 
result is ORIGIN dependent (see ORIGIN). 

• This function uses and modifies the SEED parameter (see SEED). 

• If A=0, or both A=0 and B=0, an empty vector results. 

« Repeated calls with the same arguments produce different 



results (see examples). 



13 7 2 

4?7 

6 7 5 4 

4?7 

7 4 6 3 
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GRADE UP 

syntax: 

domain: 

range: 

conformability: 

result shape: 

definition: 

note: 



examples: 



B must be numeric. 
Ordinal. 

(pp5)=l 
(p/?)«--*pB 

The result R is a vector of the indices of B suitably arranged such 
that Bin ] is the ascending sorted arrangement of the elements of B 
in which the relative order of equal elements of B is undisturbed. 

• All element comparisons are exact; this function does not use 
FUZZ. 

m Since the elements of the result are indices, the result is 
ORIGIN dependent (see ORIGIN). 

*4 7.3 "3.7 1 5.27 3.1277 
3 if 1 5 2 6 

n+R+bB'*- 2 7.5 2 918.3 7.5 

1 3 2 5 4 

BZE1 

2 2 7.5 7.5 918.3 
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GRADE DOWN 



syntax: 

domain: 

range: 

conformabiiity: 

result shape: 

definition: 

note: 



example s : 



B must be numeric 

Ordinal. 
* 

(ppB)=i 

(pi?)«--»-pS 

The result R is a vector of the indices of B suitably arranged such 
that BlR] is the descending sorted arrangement of the elements of 
B in which the relative order of equal elements of B is undisturbed. 

• All element comparisons are exact; this function does not use 
FUZZ. 

• Since the elements of the result are indices, the result is 
ORIGIN dependent (see ORIGIN). 

?4 7.3 "3.7 1 5.27 8 . 1Z77 
6 2 5 14 3 

U*-R+VB+2 7.5 2 918.3 7.5 
4 2 5 13 

Bun 

218.3 7.5 7.5 2 2 
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REPRESENTATION 

syntax: 
domain: 
result shape: 
definition: 



Rt-ATB 

A and B must both be numeric. 

If A has zero or one element the result is A» . \b . 
If A is a multi-element vector and B is a scalar, the result is a 
vector, the elements of which form the representation of B in a 
scheme with radices specified by A. 

if: S+~l+A 

then: (AtB)«-+( Ci*A)t(0*S)x(B-S\B)*S+S=0) ,S\B 

Note that if the above A has zero -value elements, all elements of 
the result whose ordinal is less than the highest zero-value element 
ordinal of A are zero. 

With general arguments, the result is obtained by using each 
vector subarray of A along the first coordinate as a radix scheme 
in forming the representation of each element of B as a corres- 
ponding vector along th^. first coordinate of the result. The cor- 
respondence is as per OUTER PRODUCT. 



examples: 10 10 10T123 

12 3 

2 2 2T3 
1-1 

2 2 2T~3 
10 1 

10 10T123 
2 3 



(decimal representation of 
1 2 3) 



(binary representation of 3) 



(two's complement representation 
of "3) 
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(yrds. , feet, inches in 135. 25 
inches) 



(results with fractional 
radices) 



10T123 
12 3 

"10 "10 "10 ~10T~123 
19 3 7 

"10T _ 123 

12T113 

9 5 (auotient and remainder of 

113-=- 12) 

1 T 1 2 . 3 4 

12 0.34 (integral and fractional part of 

12.34) 

3 12T135.25 

3 2 3.25 

0.3 2T3 
3 0.11 

2 "2T"13 

"7 1 

2 "2T~13 

"6 "1 

pO( ,0)T1 2 3 
12 3 

1 3 



10 10 10 10T6473 2196 857 42 

6 2 
4 18 

7 9 5 4 
3 6 7 2 

(3 2pl0 1)T823 457 91 147 

8 4 1 


2 5 9 4 


3 7 17 




19980800 A 9 _ g 



BASE VALUE 



syntax: 

domain: 

conf or inability: 



result shape: 



E+AiB 

A and B must both be numeric 

(ppA)>l 
(pp5)>l 
("l+pA) = l + pB jvia extension if l=~l*pA or l = l + pB 

(pi?)-«~>("l + pA),l + pB 



definition: 



If A and B are both multi- element vectors, the result is a scalar 
whose value is that represented by B in a radix scheme A. 

With general arguments, each vector subarray of A along the last 
coordinate is used as a radix scheme to evaluate each number 
whose representation is a vector along the first coordinate of B, 
the value being placed in the corresponding position of the result. 
The correspondence is as per INNER PRODUCT. 

Recalling INNER PRODUCT, note that if A and /or B are empty 
but 0*x/~l*pA and 0*x/n. p s the result will be non 

empty, consisting of addition identity elements (zeros) as required 
for the resulting shape. 

If the length of the last coordinate of A or the first coordinate of 
B is one, scalar extension along that coordinate shall occur such 
as to make the two coordinate lengths the same. 

If the length of both of the above coordinates is one, the result can 
be expressed as R+( (pA )pl) + . x£ 
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2 3 



123 





2 2 2x1 1 




5 


2X1 1 




5 


2 2 2x1 


(scalar extension of A) 


7 


2 2x1 1 


(scalar extension of B) 


LENGTH EREOE 


(argument lengths diff- 




$x 2 2X1 1 


erent) 




3 12x3 2 3.25 




135. 


25 


(inches in 3 yards. 2 feet 




. (3 Ip2)xl7 


3 1/4 inches) 


17 17 17 






2 2 2x1 3pl7 




119 


119 119 

(1 3p2)x3 lpl7 




119 


p(l 3p2)x3 lpl7 




1 1 


AHQ 3p2)x3 lpl7 
pA 




1 


A+(l 3p2)x3 0pl7 
PA 




1 


A+(0 3p2)x3 0pl7 
pA 







A+(3 0p2)l0 2pl7 
PA 




3 2 


A 


- 



















(1 2p2)xl 3pl7 




51 i 


51 51 

(2 Ip2)x3 2pl7 


(1 + pB extended to 2) 


119 
119 


119 
119 


(~l*oA extended to 3) 
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EVALUATE 



syntax: 

domain: 

conf or inability: 

definition: 



note: 



application: 



H+±B 



Character. 

(ppP)^! 

(pB}< 65535 (APL*STAR restriction)' 

The character vector B is assumed to represent an evaluable APL 
expression. 

EVALUATE interpretively evaluates this APL expression and, upon 
successful completion, returns the value of that expression (if any) 
as its result. 

Error detection and reporting are similar to that which would result 
if the expression represented by B were input for immediate exe- 
cution. 

Using EVALUATE, APL programs can be constructed which modify 
APL source expressions prior to their evaluation. 



(See examples on next page. ) 
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examples: 



iM<-5 ! 
A 



10 



2xi M- 



10 



B<-2*±SPA 
B 

1 + iff/x/ffi, ' + 3' 



l' 2*0' 
DOMAIN ERROR 
$: 2*0 

I'-vS 1 

SYNTAX ERROR 
$: i'->-5' 
1 » )DIGITS 5 * 

)£: DIGITS 5 
$: t')DIGITS 5» 



(error detection as in 
immediate execution) 



(not evaluable) 
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numeric test 



NUM+ 1 0=Q\Op • 
B«-i5 

±NUM,'B' 

C+'ABC % 
±tlUH, • iO» 



iNUM, 



t t i i i i 



nested execution 

X+ 1 (OpA+1 +A) ,(0pB+iB-R) *#),' 

^Ai?£ , PAB- , *r,((("l + p ,yl)xpj,jr)pj,j) t t t l0 i i i 

A+100 100 

B«-357.91 

3.AAREP&B 

3 57.91 

In the above example, the character vector AhREPLB contains an 
evaluate function designator as its first character. Evaluating 
AkREPAB involves first evaluating 1* A&REP&B and then evaluating 
the result of that. tl^AhREPLB results in a character vector which 
is a tailored APL expression dependent on the shape of A. 

H^ALREPhB 
Ui<-(N-*-~l+A) IS) A0pA+l*A) ,(0pB<-(B-R)*N) ,R+(N+-n.A) \B) , i0 

This expression is then evaluated, yielding the final result. 
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MBED 



domain: 

conf or inability: 

range: 

result shape: 

definition: 

examples: 



No restriction 

None 

List 

(pf?)«-+,i 

The result is a one-element vector list whose element is the 

imbedded array B 



L 

NONCE ERROR 

9L 
1 

r.ro 

UL J-J 

ABC 

E+O+L 

pE 


F+l+E 

pF 



(list cannot be displayed) 



(imbedded list element revealed) 

(E is an empty list vector) 
(F is list fill element) 



ABCD 

12 3 
4 5 6 

ABC 



12 3 
4 5 6 

ABCD 

ABC 



LS+{c'ABCD* ),(c2 3oi6),c£ 
L3C1] 

L3C2] 



L3[3][l] 

L22^I3,cL3 
L22[U][2] 



L22[4][l] 
L22[4][3][l] 
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FORMAT 

syntax: 
domain: 



co nf or inability: 



If B is numeric 



result shape: 



definition: 



note: 



application: 



If B is character - 



definition: R+-B 



R+-VE 

Numeric or character 
(pp£)>l 



(ppf?) = ppP_ 

( 1 + pi? )■*--»- 1 + pB 

("ltpn)= if 0=~l+p5 

I+t/W+1 otherwise 

where "C J] is the width required to format the Ith column of B. 

If (pp5)>5, B is treated as a restructured array Bl as described 
under DISPLAYING DATA. The columns of Bl are then formatted 
according to the rules given in that same section. This results in 
(~l+pp) character arrays FB. of column width W., and shape: 

The result is then formed by catenating the formatted columns, with 
a blank separator column between each: 



R+-F. 



where: 



Since the formatting is done according to the rules given under DIS- 
PLAYING DATA, the result is dependent on the setting of DIGITS. 
However, since the result is not actually displayed, it is not sensi- 
tive to the setting of WIDTH, which is a terminal display parameter. 

The purpose of FORMAT is to convert numeric data to character 
data which can then be suitably edited, combined with other char- 
acter data and, finally, displayed in any desired form. FORMAT 
gives the user much more flexibility in formatting output than com- 
posite data object displays allow. 
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examples: Z-mH0+i5 

X 



11 
12 
13 
14 
15 



P* 



3 1 +J 



4>Z 



5 2 



11 
21 
31 
41 
51 



X+l 2 3 4 5 
NAME+*X X 

INDEX+3 

±NAME t T ! A* INDEX), ' >7 ' 
X 
12 7 4 5 

12 3p X ABCDEF % 
ABC 
DEF 
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NULL 



syntax: 
domain: 
conformability: 
definition: 



examples: 



R+AoB 

No restriction 

None 

R+A 

In addition, if B is a non-result-returning function, no error 
occurs, as the result of B is never referenced. 

This function is primarily used for placing on one line expres- 
sions which logically (but not syntactically) constitute a single 
task. 



53 



5°3 

Z+1+ Jo 2 F 9 
Z 



(note only 5 displayed) 



(F need not be result returning) 
Right argument of TAKE is 
effectively just Y. 
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MONADIC I-BEAM 



syntax: 
domain: 

conf or inability: 
result shape: 
definition: 



examples: 



R+XB 

B must be integer ( see table below), or character. 

(pp5)=l 



(pS)<65535 
(see below) 



(pp5)=0 
(ppi?) = 

The I-beam function provides a mechanism for the user to inquire 
about certain items of system information not part of the APL 
language. The particular piece of information desired is indicated 
by the value of B, 

1. The integer values of B accepted by APL*STAR and the infor- 
mation returned are indicated in the following table. 



B 



Information 



19 Total time APL has been awaiting input from this user 
(since sign-on) . 

20 Time of day (sec. since midnight) . 

21 Total CPU used since sign-on (sec). 

22 Current amount of workspace unused (bytes) . 

24 Sign-on time (seconds since midnight). 

25 Today's date (YYMMDD 1Q ). 

26 Value of current function line number. 

27 Vector of line numbers from State Indicator. 

2. If B is character, the action taken is to perform the System 

Command indicated by B. The System Command SAVE and DROP 
may not be used. The result returned is the same as that which 
would have been reported by the command in question. If an error 
occurs in executing the command, this error is reflected to the 
I-beam function. 



24- 60 60TI20 
13 23 HI 

I 1 )DIGITS 1 



(Time is now 1:23:47 p.m.) 



0RG+x')0RIGlN 0' 
) ORIGIN 

ORG 
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DYADIC I-BEAM 

syntax: 
domain: 
conformability: 
definition: 



6 I-BEAM 

domain: 

conformability: 
range: 

result shape: 
definition: 



R+ATB 

A must be integer (see table below) 

(ppA)=o 

The dyadic I-beams are not normally used by a non-system user. 
They perform the system functions indicated below: 

A Meaning 

6 Workspace/session parameter interface 

8 Special character interface 

B must be numeric 
B[l] must be integer 
(ppB)=l (pB)cl 2 

R is numeric 

(ppi?)=0 

B[ Vindicates the workspace or session parameter being accessed. 
The result is the current value of the parameter in question. If 
(pB)=2 , the parameter is subsequently set to the value of B[2] 



B[l] 


Parameter 


Domain of B[2] 





Index Origin 


Boolean 


1 


Random Number Seed 


Integer i*B[2]<2*47 


2 


Digits 


Integer 1<B[2]<;13 


3 


Print Width 


Integer i<£[2]<;65535 


4 


Comparison Fuzz 


Real 0<B[2]<1 
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8 I. BEAM 

uuiuam, j-j luuat mo iui<cgci 

range: Result is character 



re suit shape : ' ( opR) = 

definition: The result is the special character indicated by B according to the 



examples: 



table below: 

B Character 

New Line 



V+'ABCD* ,(8l0), 'WXIZ' 

V 
a crm 

WXIZ 

■ qV 

9 (Note V is a vector of 9 characters) 
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MATRIX INVERSE, MATRIX DIVISION 



dyadic syntax: 
monadic syntax: 

domain: 



i?«-B2 



(here the left argument defaults to an 
identity matrix with shape 2pltp2. 1 ) 



A and B are numeric. 

B must be non-singular (see Solving Linear Equations) 



conform ability: 



2>ppA 
2>ppE 
( ltp/4 )■*-->! + pE (after scalar extension if A and/or B scalar) 

if 2 = ppS then ( pE ) [ 1] >( pE )[ 2] 

(necessary but not sufficient to ensure the non- singularity of B) 

if l = ppB then 0*pB 



result shape: 



definition: 



( P ;t )«-->( i + p5),(i + p/_ ) 

The result R is such that each element (if any) of +/ (A-E+ . xf: )* 
is minimized. 
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MATRIX INVERSE R+m 

mv- - j;~ ~^,^^~^^ ■iu vnnni + D in o motr-iv which ic the li=>ft invprsp nf thf» matrix R. 

The result R has a shape and value such that the matrix product with B is an identity 
matrix I: 

I+R+, xB 

Note that this requires the shape of K to be identical to the transpose of B: 

(p£)«->-p$B 

An identity matrix is one which when multiplied by any other conformable matrix results 
in that matrix: 

C+I+.xC (pC)[l]<(pC)C2] 

C^-C+.xJ (pC)[l]>(pC)[2] 

An identity matrix is a square matrix with ones along its diagonal, and all other elements 
zero. It is its own inverse. 

Matrix inverse is best thought of as a process identical to the dyadic case of matrix 
division in which the left argument is an identity matrix of conformable shape. 

The resulting product of a matrix inverse i3 and a matrix A is identical to the matrix 
division A$B when B is non- singular: 

USB )-*-*- (tUB)+.*i4 



example: _ U+R+ftB+3 3pl0 30 13 30 1 

0.125 0.375 
"1.125 1 _0.375 
0.375 0.125 
R+.xB 
10 
10 
1 

13 4 
0.12 0.16 

@2 
0.5 

pB5 OpiO 
5 
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LINEAR EQUATIONS 

A linear equation is one in which variable terms occur only to the first power; i. e. , having 
the form: 

a l X l +a 2 X 2 + "- +a n X n = C 
If only two variables are present, the equation becomes: 

a l x l + a 2 X 2 = C 

and represents a straight line. That is why equations of this form are called linear 
equations. 

It is customary to regard the last stated variable as the dependent variable and the rest 
as independent variables. The dependent variable can then be regarded as the value of a 
function of the independent variables such that the linear relationship expressed by the 
equation holds: 

-a 
X 2 = f <V = — 2 X l + % 

_a l 

is the slope of the line. 



a 2 

c 

— is the intercept on the x (function) axis. 

a 2 Z 

A linear equation with three variables: 

a l x l + a 2 X 2 + a 3 X 3 = C 

is the general equation of a plane. It expresses the linear relationship of a function of two 
independent variables: 

x 3 = f(x l' X 2 )= -iT X l— ! X 2 + iT 



In general, a linear equation involving N variables is the general equation of a hyperplane 
of N-l dimensions. It expresses the linear relationship of a function of N-l independent 
variables. 
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A set of linear equations is thus a set of lines, planes or hyperplanes depending on the 
number of variables present. All equations can be raised to the same dimension by 
supplying coefficients of zero as required. 

The solution of a set of linear equations is the location of a point common to all given lines, 
planes, etc. To determine a solution, there must be as many equations in the set as there 
are variables: the common point of two lines is their point of intersection, the common 
point of three planes is their mutual point of intersection. 

Even when a sufficient number of equations are present, a solution may not be possible. 
No common point exists for instance for two lines that are parallel. Likewise, no common 
point exists for three planes, each pair of which intersects along lines that are mutually 
parallel. 

In such cases, it is possible to show that one or more of the equations can be derived 
(with a possible difference in the constant term) from some algebraic combination of one or 
more of the remaining equations. Such an equation is said to exhibit a linear dependence 
with respect to the remaining equations. For a solution to exist in the case where the 
number of equations is equal to the number of variables present, all such equations must 
be mutually, linearly independent. 

SOLVING LINEAR EQUATIONS 

Matrix division provides a systematic way of solving a set of linear equations. Each row 
of the matrix B constitutes the coefficients of the variables for an equation. To solve a 
single set of equations, A is a vector constituting the set of corresponding constant terms 
for the set of equations, and the result R is a solution vector for the variables in the 
equation set. 

To determine a solution for a set of linear equations, there must be as many equations as 
variables. Further, each equation must express a relationship independent of (i.e., not 
capable of being derived from, yet consistent with) any or all other equations in the set. 
This criterion is determined solely by the shape and value of B. If the criterion is not met, 
B is said to be singular and a LENGTH ERROR or DOMAIN ERROR results. 
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Solve: 2x + 3y + z = 23 

x + 4y + 2z = 27 
3x + y - 2z = 10 



23 27 10g3 3p2 C114231~2 
3 5 2 

(The solution is x = 3, y = 5, z = 2) 

(The solutior. 

Solve: 5x + 2y + 3z = 23 

x + y + 2z = 5 
4x+ y+ z = 18 



23 5 1813 3p5 23112411 
DOMAIN ERROR 

$: 23 5 18S3 3p5 23112411 



(The third equation can be derived from the first two by subtraction and is thus not 
independent. Note further that if the constant term of the third equation were other 
than 18 a contradiction would result, thus illustrating that the non-singularity of B is 
the only criterion required to ensure a solution exists. ) 

Multiple sets of linear equations in which only the constant terms differ in each set can be 
simultaneously solved in one matrix division operation. Each row of the matrix B 
constitutes the coefficients of the variables for an equation as before. A is now a matrix, 
each column of which is a set of constant terms for one equation set. The result is a 
matrix, each column of which is a solution vector for the variables for the equation set 
whose constant terms appear in the corresponding column of A. 

Solve: 2x + 3y + z = 23 ( = 23) 

x + 4y + 2z = 27 (=32) 

3x + y - 2z = 10 ( = -4) 

B«-3 3p2 3 114 2 3 1_~2 
4+3 2p23 23 27 32 10 4 



a m 



3 2 
5 iJ- 
2 7 



(The solution for the first set is x = 3, y = 5, z = 2 
The solution for the second set is x = 2, y = 4, z = 7) 
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LINEAR PARAMETRIC EQUATIONS 

Anv pnuatinn that is linear with respect to its parameters, or which can be made so by a 
suitable transformation, can be used to form a linear parametric equation by substituting 
the coordinates of a point known to satisfy the equation. If as many independent points are 
known as there are parameters, then a set of parametric equations, each linear with 
respect to the parameters, can be solved to yield a set of parameter values which, when 
substituted into the original equation, results in an equation satisfying all the given points. 

The general parametric equation for a line is: 

y = ax + b 
The parametric equation of a line passing through the point (2, 5) is thus: 

5 = 2a + b 

Solving a set of two such equations determines the parameters (slope and intercept) of a 
line passing through both given points. 

Find the line passing through (2, 13) and (4, 19): 

13 = 2a + b 

19 = 4a + b 

13 1322 2p2 14 1 
3 7 

The required line is y = 3x + 7 

Find the parabola symetrical about the positive x axis which passes through (2, 2) and (12,7): 

2 
The general parametric equation is y = ax + b 

4 = 2a + b 
49 = 12a + b 

4 4912 2p2 1 12 1 
4.5 "5 

2 
The required parabola is y = 4.5x-5 
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Find the plane passing through (2, 3, 23), (.5, 2, 16), and("l.5, ".5, 2) 

(2 3 23), (.5 2 16), and ("1.5 ".5 2) 
parametic equation for a plane: z = ax + by + c 

23 = 2a + 3b + c 

16 = . 5a + 2b + c 

2 = ~1. 5a +". 5b + c 



2 4 7 



23 16 2§3 3p2 3 1 .5Z2 1 "l . 5 ".5 1 
The required plane is z = 2x + 4y + 7 



Note that 2 points are required to determine a line, 3 points to determine a plane, etc. 

Supplying the required number of points does not guarantee a solution since, for example, 
two coincident points do not determine a line nor do 3 colinear points determine a plane. 
Also, if the required line, plane, etc. is parallel to the independent variable axis, the 
parameters are indeterminant. Such cases can be shown to be the result of nonmutual 
independence of all the linear equations in the set. 

LEAST SQUARES FIT 

If more points are supplied than required, then the corresponding set of parametric 
linear equations is said to be overdetermined and the solution obtained by matrix division 
is called a least squares fit of the given points. That is, the solution is a set of parameters 
for a parametric equation such that the sum of the squares of all projections of the points 
along the independent variable axis to the curve, surface, etc. is a minimum. 

Obtain the equation of the straight line which is the least squares fit to the following points. 
(1,2), (2,2.4), (4,5.1), (5,7.3), (6,9.4), (8,18.3). 

parametric equation: y = ax + b 

X+l 2 4 5 6 8 
¥•*- 2 2 . 4 5.1 7.3 9 , ll i 8 s 3 
_7^(6 lpZ),l 
2.21 2.16 

The required line is y = 2. 21x - 2. 16 
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Obtain the equation of an exponential curve which is the least squares fit to the same points 

, x 

exponential curve equation y - ab 

take logarithms to obtain a linear parametric equation 

In y = In a + x In b 

*(®Y)@1,6 lpX 
1.370744629 1.363563134 

Tho r-pniiivaH ovr-ji^n pritial rurvp i« nnnrnximatel v 

y = (1.37)(1.38) x 

By taking the sum of the squares of the projections of the points to the curve for each case, 
for the straight line: 

+/(J-"2.16+2.21xJ)*2 

19.465 

for the exponential curve: 



+/(7-1.37xl.38*Z)*2 

0.35173374 8 



The exponential curve can be seen to provide a better fit to the given points. 
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SPECIAL CASES 

When B is a vector, scalar or empty matrix and a conformable A argument is supplied, a 
result is obtained as follows: 

examples: 12 3 4 5@1 1111 

3 (mean of elements of vector left argument) 

1H5 

. 2 (as per division) 

p3@l lp6 

1 (one element vector result) 

pi 2 3 4- 5i5 OpiO 
(empty vector result) 

p( i0)®0 OpiO 
(empty vector result) 

p(0 2pi0)ffl0 OpiO 
2 (empty matrix result) 
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APL EXPRESSIONS 10 



INPUT REPRESENTATION FORMAT 

APL expressions input from the terminal are formed according to the following rules: 
USE OF SPACES 

# Spaces must not be used in forming identifiers, 

# Elements of numeric literal vectors must be separated by at least one space. 

# At least one space must be placed between adjacent identifiers and between identi- 
fiers and numeric literal expressions. 

# Spaces are explicitly interpreted as such where they occur in character literal 
expressions. 

A vitt «r>,pr. nnr»M><t>onfp r\f qnanps is nntinrial and is icnored. 

USE OF PARENTHESES 

# Parentheses are required to delimit the extent of an expression for the Left argu- 
ment of a function where that expression is other than a. literal expression, a data 
identifier, a niladic function call, a QUAD or a QUAD-PRIME. 

# Parenthesizing of any other expression (including one already parenthesized) is 
superfluous but allowed, unless the expression is the left argument of a specifi- 
cation. 

CONVERSION OF INPUT REPRESENTATION 

Input expressions are converted to a standardized internal format upon input. Superfluous 
space characters are ignored in this conversion. Arrays are created for literal expressions. 
If any element value of a numeric literal expression exceeds the range of the machine (see 
Appendix C), a DOMAIN ERROR occurs at this point in the line when the line is executed. 
All identifiers and function designators are also converted to an internal format. It is this 
internal format that is used by the interpreter in evaluating expressions. 
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EVALUATION OF EXPRESSIONS 

ORDER OF EVALUATION 

Any expression takes the overall form of a literal, a data identifier, or a function call. In 
the first two cases, evaluation is a one-step process. If the expression is a function call, 
evaluation proceeds as follows: 

The right argument (if there is one) is evaluated first. 

The function itself is then examined to determine if it is dyadic. For primitive functions 
which utilize the same designator character for both a monadic and a dyadic function, the 
function is interpreted as dyadic if the item to its immediate left is the rightmost item of 
an expression, namely: a literal expression, a data identifier, a niladic function call, a 
right parenthesis, a right bracket, a QUAD or a QUAD -PRIME. If no such item exists, 
the function is interpreted monadically. 

If the function is determined to be dyadic, the left argument of the function is evaluated. 
If it consists of more than one syntactic element the desired left argument must be enclosed 
in parentheses. The interpreter utilizes the occurrences of the parentheses to determine 
the extent of the expression for the left argument. 

With the argument(s) evaluated, the function call is then made and any returned result is 
the evaluated result for the expression. 

The arguments, if present, are expressions in their own right and are evaluated in the 
identical manner as stated above. 

ERROR DETECTION SEQUENCE 



Error 



Typical Causes 



SYNTAX ERROR 
VALUE ERROR 
RANK ERROR 
LENGTH ERROR 
DOMAIN ERROR 

INDEX ERROR 



improper number of arguments supplied, 
variable not established (could be misspelled), 
argument rank conform ability requirement not met, 
other conform ability requirement not met. 
supplied argument not in the domain of definition, 

r»r» r»oanlt nnt in +Yia ranrro r\f r^o-Pi ni -H/-\»n «-i-F fV>o 

function. 

index out of range; applies to indexing and index 
notated primitive function calls. 
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Examples: 

The following set of statements indicates the order in which execution is performed and 
errors are detected. 

y«-l 5 4 2 7 9 
ICO. 5 + lxZ+ + J] 
SYNTAX ERROR 

ICO. 5+0 lxX+$: tl] 
ICO. 5 + lxZ+ltl] 
VALUE ERROR 

ICO. 5 + lx$: Z+l + I] 
X+2 3pl 2 3 4 3 2 
ICO. 5 + lxl+l + I] 
RANK ERROR 

110,5+$: lxZ+l+J] 
!C0.5+(3 2p0 l)xZ+l+I] 
LENGTH ERROR 

ICO. 5+^: (3 2p0 l)xZ+l+J] 
IC0.5+C2 3p0 l)xJ+l+J] 
DOMAIN ERROR 

$: I[0.5 + (2 3p0 1)xX+H-I] 
ICL0.5 + C2 3p0 l)xZ+H-I] 
IxVDtfX ERROR 

$x IC0.5+C2 3p0 l)xj+l+l] 
)0RIGIN 
1 

ICL0.5+C2 3p0 l)xZ+l+I] 
12 1 
9 12 

(Pnntirmpd rm npvt nnccp. ) 
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The following example indicates how a specific action within an expression is handled: 

A + 2 

7 

A+2 

A+A+5 
10 



ADDITIONAL ERRORS 

Message 

• NONCE ERROR 

• WS FULL 

• DEPTH ERROR 

• SYMBOL TABLE FULL 

• REF ERROR 



Cause 

operation not yet implemented. 

workspace storage capacity exceeded 
(see SIZE command). 

a function is pendent or suspended more than 
16,383 times. 

more than 65, 535 symbols have been used in this 
workspace. 

an object or list array element has more than 
16, 383 active references. 



NOTE: The maximum array size currently permitted is 65,535 elements. A NONCE 

ERROR is issued if an attempt is made to create an array larger than this size. 
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ERROR RECOVERY 

Whenever an error is detected, the system attempts to recover to the state it was in 
before the line which caused the error was executed. The following rules are used in re- 
covering from errors: 



• 



• 



• 



• 



• 



An error in a line submitted for immediate execution causes execution of the line 
to be aborted, and a message indicating the error type to be issued, along with the 
offending line and an error marker at the point at which execution in the line was 
aDortea. ±ne user is incu ic^cisicu \.\j ou^j-iixu aiwu^i ""^ **■>■•■ -**^"~— ^«~ ,_^.~~- 
tion. 

An error in a line submitted in response to a QUAD prompt (see QUAD INPUT) 
behaves as above, and the QUAD prompt is re-issued. 

An error in a line of a user -defined function behaves as above, except that in ad- 
dition to aborting execution of the line, the function is suspended on the line in 
question, and the function name and line number is issued preceding the display 
of the line. 

An error in a line executed via the EVALUATE function behaves as above, except 
that the EVALUATE function is not suspended. Control is returned to the line 
which contained the call to EVALUATE, the line is displayed with an error marker 
at the offending evaluate, and suspension and display is attempted according to the 
above rules. 

An error in a line of a locked user defined function causes execution of the line to 
be aborted, and control is returned to the line which contained the call to the 
locked function. If this line is not itself part of a locked function, the message 
<function name> ERROR is issued, along with the line and an error marker at 
offending locked function call, and suspension is attempted according to the above 
rules. If the calling line is part of a locked function, control is restored to the 
first line which is not part of a locked function, and suspension is attempted as 
above. 

An error in a System Command executed via I-beam behaves as an error in an 
EVALUATE line. 
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DISPLAYING EXPRESSIONS 

When an expression is displayed, such as in an error report or in a requested display of a 
user -defined function line, an inverse conversion transforms the internal format to a dis- 
play format. The display formatting follows the rules of canonical form. 

CANONICAL FORM 

• All displayed expressions, (omitting the error marker), must be in a form that is 
acceptable as input. 



• 



• 



Literal numeric expressions have the same form as employed in numeric data 
formatting. (See DISPLAYING DATA). 

Comments are displayed as they were entered. 

Except as required in the above points, spaces are not inserted in displayed ex- 
pressions. 
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IMMEDIATE EXECUTION 



When no other activity is taking place, the system awaits input for immediate execution , 
mis is inaicateu uy a. -pr-umpL n um cue o^o^ui xu mt; i^ n. ^^ cu* ^^v^c^^^* ~ ^^^-^ „~^ 
the left margin. In this state, the user may enter: 



» an expression to be evaluated. 
a system command. 



When all processing resulting from the line input has been completed, the system again 
awaits input for immediate execution. 

ABORTING EXECUTION OR OUTPUT 

Whenever an expression evaluation, function execution, or output is taking place, process- 
ing may be interrupted. (This is accomplished on a terminal by signalling ATTENTION. ) 

Any ongoing output is aborted. Expression evaluation is terminated at the end of the cur- 
rently executing line. If a function is executing, it is suspended immediately before execu- 
tion of the next line. 

If the currently executing line was entered in response to a QUAD input request (see below), 
the request is not satisfied, and the QUAD prompt is reissued. 



Example: 



3 2 3 U 

5 6 A (output aborted at this point) 

pX 

3 a (note specification to X was done, since 

evaluation continues until the end of the 
line is reached) 
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QUAD INPUT 

syntax: Ji*-A 

If the symbol D (QUAD) appears anywhere except in the construct □«- , it signifies that an 
expression is to be evaluated at that point, the source for which is to be supplied from input. 

At the point where a QUAD in the above stated context is reached in the execution of an APL 
source line, further execution is pendant on an evaluated result for QUAD. 

A 'prompt' to the user terminal is sent in the form: 

□ : 

at the left of a line. This is followed on the next line by indentation 6 spaces from the left 
margin. At this point the system awaits input to be submitted. 

Input must be in the form of an APL expression. Upon entering the line the APL expres- 
sion is evaluated as for immediate execution. 

Simply entering an empty line causes the □: to reappear. 

If no errors are detected on evaluating the submitted APL expression, the result obtained 
is returned as the result for the QUAD function and evaluation of the original source line 
continues. 

If evaluation of the expression input after the prompt is not possible due to some error in 
the submitted line, the appropriate error report is issued, followed by another prompt, 
with the system again awaiting input. 

The user may now resubmit the expression, correcting the error. 

The symbol CI used in this manner can be likened to an implicit result-returning niladic 
user-defined one-line function in which the user supplies the line each time the function is 
called. As such it has two properties in common with regular user-defined functions. 



• 



• 



Recursive calls can be made with QUAD by submitting as part of the input 
expression another QUAD. 

Exit from all further evaluation of expressions at all levels is possible by 
inputting after the prompt line a niladic branch: 



This provides an exit mechanism from an infinite loop requesting and evalu- 
ating input. 



11-2 
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Instead of entering an APL expression, it is acceptable to enter a system command. All 
valid system commands will be carried out. If the system command replaces the existing 
active workspace with some other workspace, such as by )LOAD or )CLEAR, request for 
input is terminated. 

If the existing active workspace is saved while awaiting input, such as by )SAVE, the 
workspace is saved with the input request status intact. In this case, when the saved work- 
space is subsequently loaded, the prompt u: will appear and again the system awaits input. | 

Examples: 

2+n (immediate execution input) 

3x5 (response to QUAD) 

17 (result) 

Another way in which QUAD appears like a user-defined function can be seen by issuing 
)SI or )SIV in response to a request for input. 

1 ,2+CKO . 5*0-1 (immediate execution input) 

0: (QUAD prompt issued) 

fflliltm 

(QUAD pendant) 

111: (prompt reissued) 

+ • (response to QUAD) 

SYNTAX EBB OR 
+$: , 

fill: (prompt reissued) 

i.n 

J3* (prompt from second QUAD) 

)SI 
U (two QUAD'S pendant) 

i 

ilp (prompt reissued) 
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3 (response to last-QUAD) 

|!|i (display from ,n«- ) 

12 3 (result) 

J - + - j (immediate execution input) 

III (prompt issued) 

"*" (exit from last execution) 
)5I 

||i|$|p (nothing pendant or suspended) 

:||||i|t|^ (system again awaits input for immediate 

execution) 
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QUAD-PRIME INPUT 

syntax: n-*-' 7 ] 

If the character ? (QUAD -PRIME) appears anywhere except in the construct "*+ , it sig- 
nifies that character data is to be obtained from input. 



At the point where a QUAD- PRIME in the context stated aoove is reacnen in me execution 
of an APT. source line, further execution is pendant on a result obtained for QUAD- PRIME. 

No prompt occurs with QUAD-PRIME other than a bell signal or keyboard unlock. The 
system simply awaits input at the left margin. 

Input consists of a line of zero or more characters. Unlike normal input of explicit 
character literals, a quote character to mark the beginning and end of the literal is not 
used. Further, the quote character is represented by itself and not by two consecutive 
quote characters. 

The explicit character literal, as input (subject to conversion of illegal characters to the 
canonical bad character), is returned as the result for QUAD-PRIME, and evaluation of 
the original source line continues until completed. 

Input of a single character results in a character scalar. Input of no characters or more 
than one character results in a character vector. 

Since all character inputs are taken literally and are not interpreted, this function cannot 
be used recursively. Likewise, system commands will not be interpreted as such. 

A single exception to the above is a special character provided solely for the purpose of 
providing an escape mechanism identical to that provided by-^for the QUAD function. 
This special character is the composite formed by overstriking the letters 'O', 'U', 'T'. 
(For terminals without overstrike capability, the mnemonic sequence is '$G. ') 

(See examples on next page. ) 
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Examples: 



™ (immediate execution input) 

ABC (response to request for literal input) 

Hlf (result) 

pH-f-D (immediate execution input) 

8* (QUAD prompt issued) 

':: f ,HI, , .Y I (response to QUAD) 

ABC (response to QUAD-PRIME) 

^illUll (display from D«- ) 

:|| (result) 

mp^xMQ 1 ^ (immediate execution input) 

)SI (response) 

§|l (three characters recieved) 

' F ' M .1+15 (immediate execution input) 

PON 1 ? (response to QUAD-PRIME) 

XOW'T (result) 

. V: (immediate execution input) 

(exit from last execution) 

(system again awaits input for immediate 

execution) 



11-6 19980800 A 



QUAD -PRIME PROMPT 

Normally, no prompt other than a bell or keyboard unlock occurs when the system requests 

input from the user. However, the user program may specify a prompt to be issued 
with the input request. This is done by specifying the desired prompt to n as follows: 



syntax: 

domain: 
conform ability: 
definition: 



examples: 



M!H-B 

The underlined portion of the above line is the specification 

proper. 

B must be character. 

(ppB)=l 

As for specification, the result is B. The character vector B 
is issued as a prompt at the next request for B input. 

NOTE that visual fidelity requires that if the user's input is 
entered immediately following the prompt, on the same line, 
the prompt becomes an integral part of the returned input. 



ft*-' ANSWER YES OR NO: 1 

ANS+E 
Mswm IBS #M mxYES 

ANS 
A9SWSM MB OM 90x1 ES 



(type YES) 



9 



(note no prompt) 
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VISUAL FIDELITY 

The underlying concept in entering a line of input is visual fidelity ; i. e. , that the appear- 
ance of the line upon submission is what is conveyed, rather than the sequence used to 
form the line. The implications of this concept are as follows: 

The position of the terminal carriage, type ball or cursor is immaterial upon 
hitting the return key. 

« The order in which characters are keyed is immaterial. 

• On terminals with a destructive overstrike (CRTs) any character may be replaced 
by any other, including blank, prior to hitting return; only the final appearance 
will be conveyed. 

ABORTING AN INPUT LINE PRIOR TO SUBMISSION 

• Position to the right of the right-most input character. 

• Signal ATTENTION. 

The system returns to the same input mode as existed prior to entering the line. 

CORRECTING AN INPUT LINE PRIOR TO SUBMISSION 

1. Position via any combination using the backspace key and /or space bar to the left- 
most character to be erased. 

2. Signal ATTENTION. 

3. Key in appended text (if any). 

4. Submit the corrected line for execution. 
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INPUT SUBMISSION PROCEDURE 



All input is submitted in the form of a line. Normally the line consists of the line entered 
at a terminal or the card image presented to the card reader. Submission is achieved by 
keying RETURN (usually) at a terminal, or on acceptance of a card by the card reader. 

CONTINUATION CHARACTER 



««v-,ni <-.+•; *-i<-r /-\f <-i ij*TQ entered and submitted 



it is possible to submit a line m pct.rt», eacn par 
as above. All line parts, except the last, must contain the continuation character $CO as 
the right-most non-space character, The continuation character in this position serves to 
indicate that the line as submitted is incomplete and is to be continued on the next submit- 
ted line part. The last part of a submitted line must not contain a terminating continuation 
character since its absence conveys that submission of the entire line is complete. 

The APL system constructs a contiguous input line by catenating left to right all consecu- 
tively submitted line parts The continuation characters, when placed as indicated above, 
are not included in the constructed input line. Any other placement of the continuation 
character will cause the character to be subsequently transformed to the canonical bad 
character and not cause action as stated above. 

When a line submitted from a terminal contains a terminating continuation character, a 
prompt for a continuation line is issued in the form: $CO at the left of a line. This is 
followed on the next line by indentation six spaces from the left margin. At this point, the 
system awaits input of a continuation line to be submitted. 



examples: 



$C0 



ABC 



$co 



Z* x ABCDEF$CO 



GUI 



+*ABCDEF$CO 



GHIJK 1 
DOMAIN ERROR 

$: + t ABCDEFGEIJK' 
Z+$CO % ABCDEFG* 
SYNTAX ERROR 

3+1": WC^ABC'DEEG 1 



(first part) 

(continue line prompt) 

(last part) 

(result) 

(first part) 

(continue line prompt) 

(last part) 

(note catenation of input) 



($CO transformed to $BC if not 
"Fight- mo st ism- space character) 
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COMMENTS 

Any executable line of APL may be appended on the right with a comment. The special 
symbol ft (verbalized 'lamp') delimits the executable portion from the comment. 

An executable line is any of the following: 

(1) a line submitted for immediate execution 

(2) a user-defined function body line (See User-Defined Functions) 

(3) a QUAD input line 

(4) an EVALUATE argument 

examples: M«-( ,A )@( p ,A )pl r MEAN VALUE OF A X S ELEMENTS 

[3] NEXT:+0*\0 = pA+l+ ,A pi EXIT IF A EMPTY 

25 36 49*D 
□ : 

0.5 pi SQUARE ROOT 
5 6 7 

ft TR-IS ENTIRE LINE IS A COMMENT 

tB/'J+ppK a IF B TRUE 1 
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FUNCTION DEFINITION 

j. o provide an opcn^cnvuG^ness lG nru, a user may supplement tne primitive functions wilh 
those he defines himself. 

The syntax of a user-defined function definition consists of a function header followed by a 
function body. The function header declares the name of the function and its syntactic form. 
The function body consists of zero or more lines of APL, each of which may be preceded by 
or consist solely of a label (see LABELS). 

FUNCTION HEADER 

In addition to the monadic and dyadic syntax of primitive functions, user-defined functions 
may be defined having no arguments (niladic syntax). 

User-defined functions may be result-returning, as are primitive functions, or non result- 
returning. 

The above criteria and the function name are established by the function header. The form 
of a function header is as follows: 



- <result>' 



<1. arg.> <function name) <r. arg.) 

< function name) <r. arg.> 

< function name) 



; <explicit local list> 



where: <result> is the local result name 

<1. arg.>is the local left argument name 

<r. arg.>is the local right argument name 

< explicit local list) is a list of identifiers separated by semicolons. 

Identifiers in the function header other than the function name (i. e., arguments, result, 
and explicit local list) declare variables local to the function environment. (See ENVIRON- 
MENT OF AN ACTIVE FUNCTION. ) 

FUNCTION BODY LINE 

The form of a function body line is as follows: At least one non-blank character must be I 

present . 

[<label>: j[<executable portion>T--[A <comment)l 
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FUNCTION CALL 

A dyadic function name FLIP having numeric arguments could be invoked by: 
2 3 7 FLIP 8 1 

If the function header for FLIP is 

R^-A FLIP B ; X ; Y 
then at the time FLIP is invoked, A has the value 2 3 7 and B has the value 8 1 . 

The process of assigning values to A and B at the time of function call is similar to spec- 
ification. 

FUNCTION EXECUTION 

Upon function call values are supplied to the function arguments (if any), and the body of 
the function is executed. 

Each line is interpretively executed in the normal right-to-left manner starting with the 
first line. 

Lines are executed in sequence in order of occurrence unless otherwise directed by a 
branch (see BRANCH). When the last line of the function is executed, if no branch is taken, 
the function exits. 

Upon completion of function execution, the value returned is the value of the local result 
at that time. If no specification has been made to the local result, no result is returned. 
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BRANCH 

Syntax: +B 

Domain: non-negative integer 

Conf or inability: (ppS)^l 

A branch must be the left-most operation on the line in which it appears. The domain of 
the argument B is integer. No result is returned from the operation. Those cases exist: 

1. If B is empty, the branch is ignored. If B is not empty, all but the first element 
are ignored. Let I«-l+B . I must be integer. 

2. If JeO l[l] + itf , where N is the number of lines in the body of the function, the 
next line to be executed will be line I . 

3. Otherwise, execution of the function is terminated and the function exits. 

4. B must be within FUZZ of a positive integer. Otherwise, a DOMAIN ERROR will 
result. 

Note that numbering of function lines is noi dependent on the index origin. Thus I (if it 
exists) is always the first line of the function, and ->-0 always causes an exit. 

INiiladic Branch 

A second form of the branch directive exists which consists solely of the branch directive 
on a line by itself: 

Execution of a niladic branch causes an exit, not only from the current function being ex- 
ecuted but from the entire set of functions in the calling sequence initiated by the outer- 
most function call, including the immediate line in which the outermost call was made. 

The exit mechanism utilised when niladic branch is invoked bypasses all result-returning 
procedures for all currently invoked functions in the calling chain. 

The purpose of the niladic branch is twofold: 

1. To provide a termination path which stops all function execution. 

2. To reinstate the workspace environment to as near as can be obtained to what 
it was prior to calling the initial function in the calling sequence. 
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LABELS 

In forming expressions which evaluate to the number of some desired function line, it may 
prove difficult to predict what that number will be. Furthermore, the number will be 
subject to change if, subsequently, additional lines are inserted in the function or some 
lines are deleted. 

The above difficulty is eliminated by the ability to reference function line numbers symbol- 
ically. This is accomplished by the use of labels. 

An identifier followed by a colon may be placed to the left of the executable portion of any 
line to be referenced. Only one label may be placed on a line. 

This identifier is the name of the label for the line. This label is local to the function 
(see ENVIRONMENT OF AN ACTIVE FUNCTION). When the function is called, it is given 
the value of the number of that line, in much the same way as the arguments are assigned 
values. The value of a label is always an integer scalar. 

Labels have a property which distinguishes them from all other variables. During their 
existence they cannot be respecified (i. e. , their value cannot be changed). Labels are 
thus the only named constants in APL. In all other respects, they are normal variables. 

NOTE 

As will be seen in the following section, label values are 
available to functions called by the function containing them. 
As labels are indistinguishable from any other variable, 
branching to such a label in a function called by that function 
will not cause a branch back to the labelled line in the calling 
function, but rather a branch to the line in the called function 
having the same line number. If no such line exists, an exit 
from the called function will occur. 
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ENVIRONMENT OF AN ACTIVE FUNCTION 

When a function is called, values are assigned to its arguments and labels. All of its other 
local variables (the result and explicit locals) become undefined (i.e., have no value). 

This constitutes an initial local environment at function call. 

A function possesses a local environment from the time it is invoked until exit from the 
function occurs. During this time the function is said to be active. 

The fact that the local environment disappears upon function exit is a useful mechanism 
for minimizing workspace requirements and for keeping the workspace from being clutter- 
ed with data objects which are no longer required. 

Since explicit locals and the result have no value until first specified, while the function is 
active, prior reference to such variables inside the function results in a VALUE ERROR. 

Also, since the local environment disappears on exit from the function, values specified 
to locals on one function call are not available to the function on subsequent calls. 

In addition to the local environment, the total function environment initially consists of the 
entire workspace environment prior to function invocation, except for those objects whose 
names are identical to identifiers appearing in the formal parameters or local list of the 
function header, or label identifiers. 

These latter objects are said to be masked while the function is active. Note that all mask- 
ing occurs at the time of function invocation, and not when subsequent specification for 
some local is first made. 

Objects in the function environment which are not part of the local environment are termed 
the global environment . 

The global environment includes, in addition to those workspace objects not masked on 
function invocation, the workspace environmental parameters Origin, Digits, Fuzz and 
Seed. 

Functions can thus make reference to objects and respecify variables which are part of 
their global environment. New global variables can also be created by specifying to a name 
not appearing in the local list. This ability provides the function with a communication 
facility separate from that provided by the argument and result parameters, and is the 
only method available to niladic non result-returning functions. 
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NESTED FUNCTION CALLS 

At any point during execution, it is possible for a function to invoke any other function 
defined in its environment. 

When a function calls a function, the calling function still remains active (since an exit 
from it has not yet occurred); however, it is no longer executing, but rather waiting for 
the called function to complete its execution. During this time the calling function is said 
to be pendant . When the called function has completed its execution, it exits back to the 
calling function, returning a result if any. 

Execution of the calling function then recommences at the point where it left off, and the 
calling function is now no longer pendant. 

Calls to non re suit -returning functions from a function must be placed alone on a separate 
line within the body of the calling function, or be the right argument of NULL, otherwise 
a VALUE ERROR will result when the line attempts to reference the non-existent result 
of the function. Re suit -returning functions, on the other hand, can appear as arguments 
in more complex expressions to be evaluated, including additional function calls. 

The environment of a function while pendant is kept intact, while the called function creates 
its own local environment. The total environment of the calling function becomes the 
potential global environment of the called function from which certain objects may be ex- 
cluded due to masking. Objects which were masked by the calling function remain masked 
to the called function. 

The origin of objects in the called function's global environment is indistinguishable to it. 
It may indiscriminately reference, change and create global objects which are either local 
or global in the calling function. 

The state of the workspace environment upon the completion of all function execution (known 
as the absolute global environment ) will be affected, however, if the inner function re- 
specifies one of these objects or creates new ones. If, on the other hand, only objects 
which were part of the local environment of one of the functions in the calling sequence 
were effected, no change to the absolute global environment would occur. 

Note that a called function's local environment is invisible to the calling function, whereas 
both its own local environment and global environment can be affected while pendant. 

The process of having a function call a function can be continued by having that function call 
another function, etc. This gives rise to a calling chain of function calls. The calls are 
said to be nested from the outermost call to the innermost one. All called functions except 
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the innermost are pendant. Local environments exist in the workspace for all the function 
cans in the sequence. Masking can occur at each call level. 

The number of calls in the call sequence is termed the depth of nest of the innermost 
function call. Nesting can occur to any level for which sufficient available space in the 
workspace exists to create a local environment for the function called at that level. An 
attempt to nest deeper than this results in the error message WS FULL and the function 
attempting to make a call is suspended on the line in which the call occurs. 

A NOTE ON RECURSIVE CALLS 

Recall that a function may issue a function call to any function in its global environment. 
As long as the called function is not masked on calling the function, it will exist in the 
function's global environment and can just as validly be called as any other function in its 
environment. 

Any call sequence in which a function calls itself or any function in the current calling 
sequence that is pendant, is said to be a recursive call. Recursive calls give rise to the 
situation where one call of a function is currently executing while one or more other calls 
of the same function are pendant in the same calling sequence. 

The fact that multiple pendant calls and a currently executing call, all to the same function 
can co-exist, in no way causes problems. This is due to the fact that each call of the 
function creates a separate local environment to be used by that function call as long as 
that call is active. In this way each function call keeps track of its own environment and 
is oblivious to all other local environments. 

Each recursive call nests deeper in the calling sequence. Since successive recursive calls 
usually emanate from the same line in the calling function, that line when executed on 
successive calls causes further recursion to occur. If care is not taken, the nesting depth 
will become excessive, filling up the workspace with local environments of pendant calls to 
the point where a WS FULL message occurs. 

A function employing a recursive call must therefore provide an alternative path to be 
taken when some limiting condition occurs which bypasses the line invoking a further 
recursive call. The limiting condition must be met by some innermost recursive call 
within an allowable nesting depth. This call must then be allowed to complete without in- 
voking further recursive calls and exit to its caller. In like manner, each called function 
in turn uses any returned result in completing its execution and exits in turn to its caller, 
progressively reducing the nesting level until the outermost call is completed, whereupon 
all function execution terminates. 
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FUNCTION EDITOR 



13 



PURPOSE 



The Aj^L^STAR system contains a uiilily called Lhe Tunc Lion editor which accepts suitable 
input in the form of a function definition, and upon completion stores in the active work- 
s n ace a defined function suitable for subsenuent executions 

The utility can also be used to display all or part of a function definition or to modify an 
existing defined function as desired. 



INVOKING THE EDITOR 

Whenever the system is awaiting input for immediate execution, the function editor can be 
entered by placing the APL character V ('del') as the left-most non-space character of an 
input line. This must be followed on the same input line with the name of an existing defin- 
ed function in the workspace, which the user wishes to modify or display, or the function 
header of a new function which the user wishes to define. 

If the syntax of the function header is invalid, or contains the name of a currently existing 
global object, the error report DEFN ERROR results, and the function editor exits. 

Notation: In the examples in this section, shaded text indicates APL system response; 
unshaded text is entered by the user. 



Vf?«-A NEW B 



Hi 



Ml 



Ill 



)FNS 



VOID 



FUN+5 
VR+FUN B 



NEW is a new function 
being created,, The 
editor prompts for an 
entry for line 1. 



OLD has 3 body lines, 
the editor prompts for 
an entry for line 4. 



VEFti ERROB 



FUN is a currently 
existing global object, 
and thus cannot be 
used as a function name, 



NOTE: The function editor can be entered while a defined function is suspended. The local 
environments may cause masking of the function being modified or created. Masking does 
not effect the ability of the function editor to access or create defined functions. Masking 
willjL, ..ho weverj prevent calling these functions until the local environments of the ac ti ve 
functions are removed. (See SI , MLADIC BRANCH) 
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SUPPLYING FUNCTION DEFINITION BODY LINES 

Upon sucessfully entering the function editor with an input line in the form as stated above, 
subsequent lines of input are implicitly considered to be consecutive lines of the body of 
the function definition, unless their form indicates otherwise. The editor 'prompts' the 
user for each such line by displaying a line number in brackets at the left of the line to be 
entered. For a function being newly created, the first prompt is [1]. For a previously 
defined function, the first prompt is [<L+1>], where L is the number of body lines in the 
previous definition of the function. 



||§| 2?+(~l+pC)n+pA 

111. 



HI C+(pA),pB 

111 



The prompt number always indicates the relative position an input body line will have in the 
completed function, unless that input is suitably annotated to override this placement. 

Overriding is accomplished by entering a line number in brackets, optionally followed by 
the body line entry all on the same input line. If only the line number in brackets is enter- 
ed, the editor responds with a prompt as entered. 

Ill C7] A+((Z<ppA) t pA)pA 

tit c e ] 

111! -*or i(pp4)*ppB 

When overriding the prompt line number, a non-integer decimal numeral with a fraction 
part of up to 4 decimal digits can be supplied. (Using more than this results in the error 
report EDIT ERROR. ) By this means, a line position in the function body between two 
previously entered lines can be indicated. 

£33 [2.3] -*0,pQ«-' DOMAIN ERROR 1 

12.H1 C2.1] 

£2, £3 +Z,lxi(o+,4) = 0+,B 

£2.23 

After entering a body line of the function definition, the editor again returns a prompt. 
The line number of this prompt is obtained by incrementing the number of the previously 
entered line by . 1*D where D is the number of fraction digits last used in overriding a 
prompted line number. (D is set to zero initially. ) 
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REPLACEMENT OF AN EXISTING LINE 

In the same manner that new lines are placed in a function definition, a previously existing 
line can be replaced with a new entry. The prompted line number is overridden by the 
line number of the existing line, and the new body entry is supplied which then replaces the 
old entry. 

£2.33 [3] LI i.4«-( (3<pp.4) sp.4 )p4 

Hi 

NOTE: The function header can be changed in this manner by designating the line to be 
changed as zero. If the entered header results in a DEFN ERROR, a prompt for line zero 
is issued and the previous function header is maintained. 

HI CO] R+A OLD B%C 

HI 



DISPLAY DIRECTIVES 

A display directive may be entered after any prompt in lieu of a body entry or override 
directive, or as the last part of the function editor invoking line. 

(A) Displaying Contiguous Lines of a Function Definition 



directive: 
action: 



example: 

directive: 
action: 

example: 
19980800 B 



LNUM1 

All existing lines from N through M are displayed followed by a 
prompt for line 1 + U , where L is the last line. If M <N the error 
report EDIT ERROR is issued followed by reissuing of the previous 
prompt. 

C2D5] 

Display lines 2 through 5. 

COM] 

All existing lines from M to L are displayed followed by a prompt 

for line 1+LL. 

If M > L no lines are displayed. 

EM- 

Display all lines from 4 to last. 
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directive: CD] 

action: The entire function definition is displayed, followed by a prompt 

for line 1 + lL . 

example: CD]' 

directive: INU1 

action: Line N is displayed if it exists, "followed by a prompt for line N. 

example: [0D3 

Display the header line and issue a prompt for line 0. 

(B) Displaying Lines Containing a Specified String 

Each of the directives discussed in (A) above can be qualified by suffixing a text string * 
enclosed by a delimiter character. Any character not appearing in the text string other 
than v and v may be used as the delimiter character. 

Lines displayed are restricted to the range defined for each case in (A), but within this 
range only those lines containing the specified string are displayed. 

For the purpose of search, all lines are regarded as ending in ten spaces. This 
facilitates locating lines with a specific last character. 

The ensuing prompt is as per the corresponding directive in (A) above. 

examples: [3Q7 ]/£•«-/ 

Display all lines from 3 through 7 in which the text string B «- 'occurs. 

CD3]/B / 

Display all lines from 3 to the last in which the last text character 
is B, or which contain the enclosed string as part of a character 
literal or comment. 

CD3/n/ 

Display ail lines of ihe function definition which have a comment. 

[7D]/:/ 

Display line 7 if it exists and contains the character: 



13-4 19980800 B 



EDITING DIRECTIVES 

For each of the display directives (B) above there exists a corresponding edit directive 
formed by suffixing a second text string using the same delimiter character. 

[#[]Af]/< stringl >/< string2 >/ 

For the range of function lines implied by the expression in brackets, all occurrences of 

OL±'.LJ.l.g J. J-li Cli-J. OUV.11 J-J.J.J.c;o CLJ- c l cjJJ-a.i^ci-1 «->jf OOiiiig £j • mO u vv ■_> kj u j. mgu j.j.4.t*.jr u\/ wj. uiuvj^viiuv/ui, 

length including zero. 

If string 1 is empty, an entire line is matched. 

L3D7]/4[1]MC1;1]/ 
Replace all occurrences of Aill with All;ll from line 3 to 7 inclusively. 

IU1/AX/AI/ 
Replace all occurrences of AX with AY in the entire function definition. 

[3D]//J?i-iO/ 
Replace line 3 with R <-20 

CD6]/// 
Delete all lines from 6 to last inclusively. 

EDITING ACTIVE FUNCTIONS 

Any editing of a pendant or suspended function which would change the number or position 
of parameters, locals or labels results in either a DEFN ERROR with the change ignored, 
or SI DAMAGE when the function is closed. 

CREATING SEPARATE VERSIONS OF A FUNCTION 

If while editing a non-active function, the name of the function is changed by editing the 
function header, then upon exit from the editor, all such changes will be reflected in a 
user defined function having the new name supplied. The old version of the function will 
still exist under the old name. Both function definitions will be available for subsequent 
editing. 
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TERMINATING THE FUNCTION EDITOR 

When the user is satisfied with the function definition he has supplied to the editor, or with 
any changes or displays he may have requested, he may indicate termination from the 
editor by placing a y ('del') as the last non-blank character on any input line. Upon success- 
ful completion of any request of the input line, exit from the editor occurs and the system 
awaits input for immediate execution. 

Example: 

r'3] [2D3V 

r 23 **axiv/r;';'*o 1 if 91 1;? ziixrp 

(system awaiting input for immediate execution) 
VDATE 

£63 v 

(system awaiting input for immediate execution) 

If, however, the request cannot be accomplished, the appropriate error is issued and exit 
from the editor does not occur. Instead an appropriate prompt is issued. 

As part of the function exit procedure, the lines of the function definition body are assigned 
contiguous integer values starting with one, independent of the ORIGIN setting. 

FUNCTION EDITOR ONE-LINERS 

For an existing function, the line invoking the editor can specify a one-line addition or 
replacement or a display directive, followed by a closing V . Thus a single input line can 
invoke the editor, direct one task to be done, and cause exit from the editor, with the 
system then awaiting input for immediate execution. 



Example: 



VSQUISELUlV 
VE+SQU1S8 X\h 
ill L+X*1+X+X.1*X 

C23 i?*-~iKO+L)v:u£)/i+x 

(system awaits input for immediate execution) 

VOLDL2.51 i?«-("l + pil)ritpBV 

(system awaits input for immediate execution) 
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SUMMARY 

A complete summary of possible input combinations for invoking and using the function 
editor are listed below. Note that the character # may be used in place of D in function 
editor directives. 



To invoke the editor (new function): 



V < function header > { v 3 



Tn i 



invoke the editor (existing function): V < function name > f <line entry > ~) 

) < display directive >> 
/ <edit directive > \ 



To enter (or replace) a line: 

To display line N: 

To display all lines from N to last: 



f_ [ < line number > ] }<line text > 

[ ND ]£v] 
[ON ]{v] 



To display the entire function definition: [ D ] { v } 



To display all lines from N to M 
containing string: 

To edit a line: 

To edit all lines from N to M: 

To delete a line: 

To delete all lines from N to M: 

To exit from the function editor: 



[ N □ M ] / < string > / 

[ N D 1 / < stringl > / < string2 > / { v } 

[ N DM ] / < stringl > / <string2 > / X 7 j 

[ ND ]/// £v.} 
[ NQ M ] ///{ v} 
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SYSTEM COMMANDS 14 



INTRODUCTION 

In addition to the APL language, the APL system provides for an additional method of com- 
munication in the form of system commands. System commands complement the facilities 

providea in ine afl., language anu anow inc uoci ^ ihuuU^ , v^j cu*~ ^v.~~.. ~-» ^ 

ing environment. 

SYNTAX 

) <eommand name> -f< parameter list>} 

The above is the most general syntax of a system command. The valid syntactic form for . 
a specific command will be stated under the description of that command. Items in the 
parameter list are delimited from each other and from the command name by one or more 
spaces. Any error in the syntax of the command results in the error report INCORRECT 
COMMAND. 

DOMAIN 

Certain system commands can have numeric parameters. The domain of these parameters 
is stated for each such command. Any value not in the required domain results in the error 
report INCORRECT COMMAND. 

INPUT REQUIREMENTS 

System commands will be interpreted as such in any of the following input situations: 
» the system is awaiting input for immediate execution. 
» the system is awaiting quad input (quad prompt at left). 

In each of these cases, an input line in which the left-most non-space character is a right 
parenthesis will be interpreted as a system command. 

Although upper case letters are used to form the names of the commands, lower case 
letters are accepted as equivalent to upper case in the command name. 
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Only one system command may be entered on any one input line. 

Nothing else in addition to a system command may be entered in an input line. 

If the first N letters of the command name are required to uniquely distinguish the command, 
the first N or more letters of the name may be used in lieu of the complete name. 

CATEGORIES OF SYSTEM COMMANDS 

Listing the active workspace objects. 
Defining and listing functions. 
Erasing global objects. 
Debugging aids. 

Determining and altering workspace environment parameters. 
Altering workspace size. 
Saved workspace facilities. 
Termination of APL session. 

Examining and altering display device parameters. 
ACTIVE WORKSPACE 

Each currently active user is provided with an environment in which to process his data. 
This environment is called the active workspace. 

The active workspace is a directly accessible storage allocation sufficient in size to contain 
the workspace objects currently defined, the function environments of currently active 
functions, the state indicator, stop lists, and the four environmental parameters: ORIGIN, 
DIGITS, FUZZ and SEED. 

For APL*STAR, the size of a workspace is user specifiable. For APL*STAR, the maxi- 
mum size of an active workspace is installation dependent, but is in the order of 256 pages. 
Any attempt to exceed the current capacity of the workspace results in the error report 
WS FULL. 

The active workspace has provision for an identification (ID) in the same format as 
saved workspaces. (See WORKSPACE IDENTIFICATION. ) 
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CLEAR COMMAND 

syntax: )CLEAR 

action: • provides an active workspace with the following: 

1. workspace ID empty 

2. no objects 

3. empty state indicator 

4. ORIGIN 1 

5. FUZZ IE" 10 

6. DIGITS 8 

7. SEED 48131768981101 

8. input mode: awaiting input for immediate execution 

9. SIZE 52,736 (bytes). 

successful completion of the command is indicated by the report 
CLEAR WS. 

example: 

) CLEAR 
CLEAR WS 
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ACTIVE WORKSPACE INVENTORY 

A system command listing global object names exists for each kind of workspace object. 
VARS COMMAND 



syntax: 
action: 



note: 



)VARS [<NAME 1> £<NAME 2>} ] 

lists the names of global variables currently defined in the active 
workspace in alphabetic order; in the range NAME 1 to NAME 2 
inclusive. If NAME 2 is omitted, all variables following NAME 1 
(inclusive) are listed. If no parameters are given, all variables 
are listed. 

Alphabetic sequence is as follows: 

0-9 

A-Z 



a-z 

A 



s 



note: 



NAME 1 and /or NAME 2 need not be defined, referenceable, or of 
the same object type as those names being listed. 



examples: 



TAb+T_b+-b+Ac-*-rA-*-A3-*-£2+AJ+AS+8 

) VARS 

A3 AJ Ac T_b TAb b rA A5 c f 2 

)VAR5 TAb 

TAb b rA A5 62 

)VARS Ab r 

Ac T_b TAb b rA 
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FNS COMMAND 

syntax: 
action: 

OBS COMMAND 

syntax: 
action: 

LVARS COMMAND 

syntax: 
action: 



)FNS £ <NAME 1 £ <NAME 2 >} } 

lists the names of user-defined functions currently existing in the 






)OBS { <NAME 1 >£ <NAME 2 >} } 

Lists the names of all types of global objects currently defined 
in the active workspace in alphabetic order, (see)VARS). 



)LVARS £ <NAME 1 >£ <NAME 2 >} 3 

Lists the names of active workspace variables currently having 
a value, in alphabetic order (see)VARS), 



GRPS COMMAND 

syntax: 
action: 



)GRPS £<NAME1> £ <NAME2 > }} 

lists the names of group definitions in the active workspace in 
alphabetic order (see )VARS). 



GROUPS 

A group is a named set of potentially existing global workspace objects. It is useful to be 
able to reference a package set of defined functions and their global variables as a group 
when using )COPY , )PCOPY and )ERASE (q.v. ). A group is defined by a group de- 
finition which, when supplied, is itself a workspace object. 

A group definition is a named set of identifiers. The name of the set is the name of the 
group. The identifiers are names of potentially existing global workspace objects. If and 
when a global workspace object exists having a name identical to an identifier in the group 
definition, it is a member of the defined group. A group definition is supplied using the 
)GROUP command. 
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GROUP COMMAND 

syntax : 
action: 
error report: 



)GROUP < group name > < identifier list > 

creates a group definition. 

NOT GROUPED - NAME IN USE. 



The group name is the same as the name of an existing function or global variable. 
REFERENCING GROUPS 

When a reference is made to a group via the )COPY , )PCOPY or )ERASE commands, 
reference is made initially to the group definition in the indicated workspace, and addition- 
ally to all existing global objects in that workspace referenced by identifiers in the identi- 
fier list. Such objects are said to referents of the corresponding identifiers. 



example: X+Y-rZ+T+^DATA ' 

)GROUP Gl X Y G2 
) GROUP G2 Z T 
)SAVE WS 

74/09/03 13:47:06 
) CLEAR 

CLEAR WS 

)C0PY WS Gl 

SAVED 74/09/03 13:47:06 



)GRPS 

Gl G2 

)VARS 

X I 

)GRP G2 

Z T 



(note group definition G2 
is copied as it is a 
referent of Gl, but 
Z, T, the referents of G2 
are not copied) 



ALTERING A GROUP DEFINITION 

(a) Any general change in a group definition. 

Merely issue a new )GROUP command using the same group name with an 
appropriate identifier list reflecting the new grouping desired. 

)GR0UP X A B C 
) GROUP X P Q 
)GRP X 
P Q 
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(b) Dispersing a group. 

)GROUP < group name > 

If a group command consists solely of a group name, it implies an empty identifier 
list, and thus a group with no defined members. This causes any previous group 
definition by that name to be destroyed, and no new one to be formed. 

DISPLAYING A GROUP DEFINITION 

A group definition can be displayed via the )GRP command. 

GRP Command 



syntax: 
action: 

error report: 



example: 



)GRP < group name > £ < NAME1 > £ < NAME 2 > } } 

the identifier list of the group definition is displayed in alphabetic 
order (see )VARS). 

OBJECT NOT FOUND 

< identifier list > 

indicates a group definition could not be found in the active work- 
space with a name identical to the identifier listed. 

)GROUP I A C F B Z 

)GRP X 

A B C F Z 

)GRP IBM ' 

B C F 



GENERAL NOTES ON REFERENCING GROUPS 

1. )COPY and )PCOPY references to groups refer to the group definition and group 
members existing in the workspace being copied. 

2. If )PCOPY is used to copy a group and a global object in the active workspace has 
the same name as the referenced group in the workspace being copied, no copying 
using that group name can occur. 

3. )ERASE reference to a group refers to the group definition and existing group 
members in the active workspace. 

4 . Creation, modificaliohr^^ can: occtir-only in the 
active workspace and only reference the group definition, not its members. 
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ENVIRONMENTAL PARAMETERS 

In all environmental parameter commands, if no parameter value is supplied, the para- 
meter is left unchanged. The previous value is always reported. 

ORIGIN COMMAND 

syntax: )ORIGIN i J } 

action: • ORIGIN is set to the value supplied. 

• The previous value of ORIGIN is reported. 

note: ) CLEAR sets ORIGIN to 1. 

example: ) OR I GIF. 

1 

) ORIGIN 

i 

) ORIGIN 



DIGITS COMMAND 

syntax: ) DIGITS £<integer>} i <Integer<l3 

action: • DIGITS is set to the value specified. 

» The previous value of DIGITS is reported. 



consequence: DIGITS is used in numeric element formatting in formatting output 

displays and by the format primitive function (see Displaying Data. ) 

DIGITS is the maximum number of significant digits that can 
appear in a numeric element representation display. 

note: )CLEAR sets DIGITS to 3. 

example: )DIGITS 

.8 

) DIGITS 12 

8 

) DIGITS 
12 
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SEED COMMAND 

syntax: )SEED f<integer>} 1 < integer < 2*47 

action: # SEED is set to the integer specified 

« The previous value of SEED is reported. 

examples: )SEED 

4.8131769S13 

)SEED 1296 53 
4.8131769£13 

)SEED 
129653 

note: )CLEAR sets SEED to 48131768981101 



Valid Settings for SEED 

The randomness of generated numbers is very dependent on the setting of SEED. Good 
randomness is achieved by numbers whose binary representation contains a fairly even- 
distribution of ones and zeros. 

Zero, powers of 2 and small numbers should not be used. 

When to set SEED 

While debugging an APL program that uses the primitive functions Roll or Deal it is highly 
desirable that the same sequence of random numbers be generated on each test, so that 
successive sets of results may be readily compared. This can be accomplished by reset- 
ting the SEED to the same value prior to each test. 

An alternative procedure would be to )SAVE the workspace prior to each test; then 
)LOAD the saved workspace after execution and evaluation of each test, but prior to 
modifying any functions or test data. 



19980800 B 14_9 



FUZZ COMMAND 

syntax: 
action: 

note: 



)FUZZ £N } OS N <1 

FUZZ is set to the value supplied. 

The previous value of FUZZ is reported. 

)CLEAR sets FUZZ to 1E"10 



ALTERING WORKSPACE SIZE 

Although the workspace at all times has a fixed capacity for storage, the user is able to 
alter this size at any time that he feels the current size is inappropriate. He may reduce 
it to exactly match the amount he has in use, or expand it to the maximum size for which 
he is authorized. 



SIZE COMMAND 

syntax: 

action: 

error reports: 



)SIZE { N } 

where N is the number of bytes of capacity desired 

The workspace size is set to 16x|"tf*16 bytes. 

The previous size is reported. 

WS FULL - N is less than the amount of storage currently in use c 

DOMAIN ERROR 

N is greater than the maximum amount for which this user is 
authorized. 
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ERASING GLOBAL OBJECTS 



ERASE COMMAND 

syntax: 
action: 



error report: 



) ERASE <object name Iist> 

Global objects having names corresponding to those in the object 
name list are erased from the active workspace. 

If a name in the object list is a group name for which there is 
a group definition in the active workspace, then in addition to 
erasing the group definition, all referents in the group definition 
are erased. If one of the referents is another group definition, 
it is dispersed. 

If a referenced object cannot be found no message is reported, 
since this is the desired result upon completing the command. 

SI DAMAGE 

Active user-defined function was erased. 



example: 



VI 



Fl 



V2 



Fl 



)VARS 

V2 73 

)FNS 

F2 F3 

) ERASE VI F 2 
) VARS 

)FNS 
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DEFINING AND LISTING FUNCTIONS 

In addition to using the function editor, functions can be created using the DEFINE 
command and can subsequently be displayed via the DISPLAY command. 



DEFINE COMMAND 

syntax: 

domain: 
conformability: 



definition: 



)DEFINE <VARIABLE NAME > 

Let the variable name be B. Then the following constraints must 

be satisfied: 

B must be list. 

All elements of B must be imbedded character vectors. 



(ppB)=l 

(pB)-N+l 1 

N>0 t tf<6 5 534 \ 
(ppB[J])=l 1 
(p5[I])<65535 j 



where N is the number of body lines 
in the function represented 



for all TeipZ? 



The first element of B must represent a legal function header, 
starting with a ' V'„ Subsequent elements of B must represent- 
legal function body lines. 

If B represents a legal function, the function is defined as a 
global object, replacing any existing function of the same name. 

If the function is suspended or pendant, definition proceeds only 
if the local environments of all suspended and pendant calls are 
still valid under the new definition. An exception to this rule 
concerns label values. If an existing labeled line occupies a 
different position in the new definition, definition still proceeds 
even though the value of the label is not updated in the local en- 
vironments of suspended or pendant calls. 
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error reports: 



DEFN ERROR 

a) The named variable did not represent a legal function. 

b) The function represented by the named variable has a 
different local environment from that of a suspended or 
pendant function of the same name. 



B is not the name of a defined variable. 



DISPLAY COMMAND 

syntax: 



range: 



result shape: 



definition: 



error reports: 



)DISPLAY < FUNCTION NAME > -[ < VARIABLE NAME > } 

Let the name of the variable specified be R. Then the following 
rules apply to the result R. 

R is a list 

All elements of R are imbedded character vectors. 

(ppi?) = l 

( pi? ) --J/-!- i where N is the number of body lines 
in the function represented 

(ppi?Cr:)^l for all IexpF. 

The first element of R is a character representation of the 
function header in canonical form, starting with a ' V. 
Subsequent elements of R are a character representation of the 
body lines of the function in canonical form. Lines with labels 
are preceded by one blank. Lines without labels are preceded 
by two blanks. Comments are preceded by four blanks. 

If no variable name is given, the display of the function is 
reported. 

DEFN ERROR 

The function name is not an unlocked function 

INCORRECT COMMAND 

The variable name is neither undefined nor the name of a 
currently defined variable. 
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example: 



14-14 



LlSTl-(c*VR+A FUNZ B ! ) , ( c 'R+A+2XB ' ) , c ' P+R \B*2 ' 
)DEFINE LISS1 
)DISPLAY FVi;3 
VP+A FUl'3 B 
i?-K4 + 2x3 

R<rpjB*2 

)VAES 
LIST1 
)FNS 
FUN 3 
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DEBUGGING AIDS 



Si COMMAND 

syntax: 
action: 



note: 



)SI 

The )SI command produces a display of the State Indicator , a list 
of all the function calls that are currently active, displayeu in 
reverse order to the sequence of the calls; i. e. , t±±e mcs, ^eep-y 
nested call in the current sequence is at the top of the list. 

The line on which the function is pendant or suspended is placed in 
brackets after the function name. Function calls that are suspended 
are flagged with an asterisk (*). 

Although not generally advisable, it is possible to initiate an 
additional calling sequence after a current sequence is suspended. 
If this is done, the state indicator will reflect the complete status 
of all such stacked suspended calling sequences, the most current 
listed first. 

Each issuing of a niladic branch will remove the local environments 
of the most current calling sequence, and remove the correspond- 
ing entries in the state indicator up to the next suspended function. 
Thus in order to completely clear the state indicator, it is neces- 
sary to issue as many niladic branches as there are asterisks 
(suspensions) in the state indicator. 

(See examples on next page. ) 
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examples: LISTl-*-(c*VE+A FUN1 B ,Z ' ) ,c 'R+A+FUN2 J" 

) DEFINE LIST1 
) DISPLAY FUN1 
VR+A FUN1 B;Z 
R+A+FUN2 B 

LIST2*-(<z ' VR+FUN2 C » ) , c ' + nTHIS LINE IS WRONG ' 
)DEFINE LIST2 
) DISPLAY FUN 2 
VR+FUN2 C 

+fiT3IS LINE IS WRONG 

2 FUN1 3 
SYNTAX ERROR 
FUN2L11 $ : + nTHIS LINE IS WRONG 

)SI 
FUN2H1 * Indicates FUN2 is suspended on line 1. 

FUNllll Indicates FUN1 is pendant on line 1. 

4 FUN1 5 
SYNTAX ERROR 

FUN 2[1] $: + nTHIS LINE IS WRONG 

)SI 
FUN2H1 * 
FUNllll 
FUN2H1 * 
FUNllll 



Second suspended calling sequence. 
First suspended calling sequence. 



)SI 

FUN2H1 * 
FUNllll 



First suspended calling sequence (environment 
of second sequence is removed from the work- 
space). 
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)SI 



(blank) 



State indicator is empty, 
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SiV COMMAND 

syntax: )SIV 

action: The action of SIV is similar to SI, but in addition to providing the 

function call names and line numbers, the local variables (including 
labels, arguments, and result) for each function call are listed. 

example: using tbe same functions as the example in )SI : 

2 FUN1 3 
FUN2H1 .f: + nTHIS LINE IS WROIJC 

)SIV 
FUN2LH * 

C R < ~zp^ Note: not the same variable 

FUNllll 




Note: no global variables 



R 
VALUE ERROR 
$i R 



No value has been assigned to the 
result variable for FUN2 
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STOP COMMAND 

The STOP command provides a useful debugging tool for allowing examination of the function 
environment at strategic points in the function. 

syntax: )STOP <function name> £<function line numbers (stop list) >} 

action: # The line numbers in the stop list are added to previously set line stops 

(if any). 

• The function is modified so that it will be suspended prior to starting 
execution of the lines specified. 

consequence: If during subsequent execution of the named function a stop-designat- 

ed line is encountered for execution, suspension of the function 
occurs on that line prior to its execution. 

The function name followed by the line number in brackets is output, 
followed by a request for input for immediate execution. 

notes: • The line numbers need not be in order in the stop list. 

• If line 1 appears in the stop list, suspension occurs initially 
before any lines of the function are executed. In this case, all 
local variables are undefined except for the arguments. However, 
any masking of the global environment will have taken place. 

• If line appears in the stop list, suspension occurs 
immediately prior to exit of the function. The environ- 
ment of the function is still in effect at this point. Exe- 
cution is resumed by-*0. 

• Issuing a new STOP command for the same. function causes 
the new stop list to supersede the old one. 

• Complete removal of stop control for a function is provided by 
issuing a STOP command for the function with an empty stop list: 

)STOP <function name> 
error reports: INCORRECT COMMAND 

Named object is not an unlocked function. 
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examples: 



LISTl-KOVI?-^ FUNZ B' ),(c'f?-M + 2xS ! ) ,c ' J?«-j?rB*2 ' 
)DEFINE LIST1 
) DISPLAY FUN3 
VE+-A FUNS B 
i?-t-A + 2xB 
J?-f-i?rS*2 

)5T0P Fi//l/3 2 

5 FZW3 3 
Fi/ff3[2] 

)SI 
F£W3[2] * 

A 
5 

B 
3 

R 

11 

-*-2 

11 

)BI 

)STOP FUN3 
5 ?W/3 3 
11 
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SAVED WORKSPACES 

Each APL user is provided with facilities for preserving his user environment (the active 
workspace) at any point in a session as a saved workspace. This allows him to subsequent- 
ly reinstate that workspace as the active one, thus reestablishing the environment exactly 
as it was when saved. 

A user may maintain as many saved workspaces as he wishes. Each stored workspace has 
a workspace identification (ID) by which it can be referenced. Facilities exist for updating 
or deleting individual workspaces and for incorporating specified objects or groups from 
saved workspaces into the currently active one. 

In addition, the user is provided with a security of access to, and erasure or modification 
of, his saved workspaces by a password and user key facility. 



WORKSPACE IDENTIFICATION 

<workspace ID> := <workspace name> {:< password >} 

Every workspace has an identification (ID) consisting of: 

• a workspace name. 

• an optional password. 

The workspace name is formed according to the same rules as apply to an identifier, but in 
addition is restricted to the character set and number of characters allowed by the host 
operating system. 

In this system, the name can be up to 7 characters long and cannot include the characters a , 
and £ . The password is formed according to the same rules as apply to an identifier. 

Defaults 

If the workspace ID is omitted in a command which references a workspace, the workspace 
ID defaults to that of the currently active workspace. 

If the password is omitted, it defaults to no password. 
No default is allowed for COPY, PCOPY or DROP. 
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Reports 

Several commands report workspace ID'S. In such cases, the following rules are used: 



The password (if any) is never reported. 

If there is no workspace ID, it is reported as CLEAR WS. 

The timestamp (if any) is reported as: 

WYY/MM/DDfcHH:MM:SSfc 

If the workspace has no timestamp, a blank timestamp field is reported. 

If a workspace ID was not supplied with the command, the active workspace ID 
is reported following the timestamp. 
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SAVE COMMAND 

syntax: 
action: 



error reports: 



consequences: 



)SAVE {<workspace>} 

• A saved workspace identical to the currently active workspace 
is created. 

• The active and saved workspaces are designated with the work- 
space ID supplied and with a current time stamp. 

• A defaulted password causes the password on the active work- 
space to be used. 

• Any previous saved workspace bearing the ID of the newly 
saved one is dropped, if this is allowed. 

• Upon succesful completion of the command; the following is 
reported: 

< TIMESTAMP> {<WSID>} 

• WS LOAD ONLY 

An attempt was made to save this workspace in another user's 
library. 

• NOT SAVED - THIS WS IS < active workspace ID > 

An attempt was made to SAVE a workspace under an ID or a 
currently existing library workspace while the active work- 
space ID was different. (This protects one from inadvertently 
overwriting a saved workspace. „ . . If such action is intended, 
precede the SAVE command with a )WSID command (q. v. ) 
supplying the ID desired. ) 

• NOT SAVED - THIS WS IS CLEAR WS 

)SAVE with no parameters was issued with an active workspace 
having no workspace ID. 

• If a SAVED workspace ID includes a password, subsequent 
referencing of the workspace must include the password. 
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examples: 



X+3 



)SAVE XIS3 (save as workspace named XIS3 

and set WSID to same) 

74/03/09 15:37:04 XIS3 an 

)SAVE (resave under same name) 

74/03/03 1 5 ; 3 7 ; 2 9 

)SAVE XIS3:I (resave with password) 

74/03/0S 15:37:43 

) CLEAR 
CLEAR WS 

1+1+ X+3 

)SAVE 
NOT SAVED - THIS WS IS CLEAR WS (cannot save as CLEAR WS) 

)SAVE XI S3 
NOT SAVED - THIS WS IS CLEAR WS (XIS3 already exists) 

)WSID XIS3 (declare WS ' XIS3,) 

CLEAR WS 

)SAVE 
74/03/09 15:38:23 
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LOAD COMMAND 

syntax: )LOAD £< workspace ID>} 

actlon: • A search is made for a workspace with workspace name as 

indicated. 

• If the workspace is found and includes a password in its ID, 
a check is made for a match with the password supplied,, 

• The indicated workspace is loaded as the active workspace, 
replacing the previous environment of the active workspace. 

• The active workspace ID becomes the ID of the loaded work- 
space. 

• Upon successful completion of the command, the following 
is reported: 

SAVED <TIMESTAMP> { WSID > } 

error reports: # WS NOT FOUND {<WSID>} 

no workspace by that name. 

• WS LOCKED 
password does not match. 

• WS NOT LOCKED 

password given for unlocked workspace. 

STATE OF SAVED WORKSPACES 

A workspace is always saved in the state which exists at the time of the save. When the 
workspace is subsequently loaded, it is loaded in that state. 
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examples: 



X«-3 

)SAVE XI S3 
74/03/09 15:44:59 
) CLEAR 
CLEAR WS 

)VARS 

)LOAD XIS3 
SAVED 74/03/09 15:44:59 
) VARS 
X 



X+2 

)L0AD 
SAVED 74/03/09 15:44:59 XIS3 

X 
3 

)LOAD XISSiPQR 
WS NOT LOCKED 

)SAVE XIS3:ABC 
74/03/09 15:47:04 
)LOAD XI S* 
WS NOT FOUND 

)L0AD XIS3 
WS LOCKED 

)LOAD XISZ'.TQR 
WS LOCKED 



14-25 
19980800 B 



COPY COMMAND 

syntax: 
action: 



note: 



error reports: 



)COPY < workspace ID > { < object list > } 

A search is made for the workspace indicated as for )LOAD. 

If found, the specified objects are searched for in the workspace 
global environment and, if found, copied into the active work- 
space, replacing any existing global object in the active work- 
space having the same name. 

If a specified object is found to be a group definition in the refer- 
enced workspace, then in addition to copying the group definition, 
all referents in the group definition are copied. 

If no object list is provided, all global objects in the referenced 
workspace are copied. 

Successful completion of the command results in the report: 

SAVED < TIMESTAMP > £<WSID>} 

Only global objects are copied. The function local environments, 
state indicator, stop lists and environmental parameters cannot be 
copied, and those in the active workspace are undisturbed. 

WS NOT FOUND WS LOCKED, WS NOT LOCKED 

as for LOAD 

OBJECTS NOT FOUND 
< identifier list > 

the objects reported in < identifier list > could not be found 
in the referenced workspace. 

SI DAMAGE 

an active user-defined function was erased. 
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examples: 



Z«-3 

)SAVE XI S3 



/t/U3/ 






X+2 

)C0PY XI S3 
SAVED 74/09/03 15:43:27 

X,I 
3 7 

Z«-2 

I«-5 

)C0PJ ZIS'S J 

2 7 

) GROUP GRP1 X 1 A 

)SAVE 
74/09/03 15:44:03 ATS3 

)CL£Ai? 
CLEAJ? WS 

)COPY XI S3 GRP1 
SAVED 74/09/03 15:44:03 

)VARS 

X I 

)GRPS 

GRP1 

)GRP GRP1 

A X I 

)C0PI XI S3 A 
OBJECT NOT FOUND 
A 
SAVED 74/09/03 15:44:03 



(copy all global objects) 
(X, Y restored) 

(copy Y only) 

(Y only restored) 
(create group GRP1) 

(copyGRPD 

(copied as existing referent of GRP1) 

(A is a referent but does not exist) 
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PCOPY COMMAND 



syntax: 
action: 



error reports: 



examples: 



)PCOPY < workspace ID > {< object list > } 

Action is identical to COPY except that objects whose names are 
identical to the names of objects in the active global workspace 
are not copied, thus protecting the objects already there. 

WS NOT FOUND - as for LOAD 
OBJECTS NOT FOUND - as for COPY 

< identifier list > 

note that objects which would have been prevented from 
being copied if found, are nonetheless reported if not found. 

OBJECTS NOT COPIED 

< identifier list > 

the objects in < identifier list > had the same names as 
existing global objects in the active workspace. 

X+3 

)SAVE XI S3 
74/09/03 15:51:17 

X+2 

) ERASE Y 

)PC0P1 XI S3 X I Z 
OBJECTS NOT FOUND 
Z 

OBJECTS NOT COPIED 
X 
SAVED 74/09/03 15:51:17 

)VARS 
X I 

X,Z 
2 4 



(protect copy all global 
objects in XIS3) 

(Z not in saved XIS3) 

(X is not copied since 
it exists in active WS) 



(Y is copied, 
X is preserved) 
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DROP COMMAND 

Syntax: fJ-/£\KJJT <^ VVUin-b^a^i- XJ— ^ 

action: • A search is made for a workspace with the specified name, 

as for )LOAD. 

# If found, the workspace is removed, if this is allowed. 

* The date and time when dropped are displayed to indicate 
successful execution of this command. 

error reports: as for )LOAD 

, WS LOAD ONLY 

An attempt was made to drop this workspace. 

x , Tr „ Tr-r-^t^ ^cT*e a te it^ 

)SjiV£i AJ.DO ,uc„i.c -., 

~ . „ „ (time stamp) 

74/03/09 16:01:14 

)L0AD 0- oad i1; ) 

SAVED 74/03/09 16:01:14 XISZ (time saved) 

)DE0P XISZ'.PQR (drop it) 
WS NOT LOCKED 

)DR0P XI S3 

73/03/09 16:01:37 (time dropped) 



)L0AD XI S3 
WS NOT FOUND 

)SAVE XIS3-.ABC 
7 4/03/09 If. : 01: 58 
)DR0P XI S3 
WS LOCKED 

)DR0P XIS3-.ABC 
74/03/09 16:02:11 



(XIS3 no longer exists) 
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WSID COMMAND 

syntax: )WSID {< workspace ID > } 



action: 



note: 



example: 



(a) No parameters provided. The active workspace time stamp 
and ID are reported. 

an empty ID is reported as CLEAR WS; this does not necessarily 
mean a CLEAR workspace. 

(b) If a workspace ID is provided, it becomes the ID of the active 
workspace. The active workspace time stamp and previous ID 
are reported. 



)WSID 

CLEAR WS 
X+3 
) WSID 

CLEAR WS 
)SAVE XI S3 
74/03/09 16:12:42 

)WSID 
74/03/09 16:12:42 XIS3 
J>4 

)WSID XI S 4 
74/03/09 16:12:42 XIS3 
)SAVE XI S3 
NOT SAVED - THIS WS IS XI SH 
)WSID XIS3 
74/03/09 16:12:42 XlSk 

)WSID 
74/03/09 16:12:42 XIS3 

)SAVE 
7 4/03/09 J.6:13:23 XIS3 

) WSID 
74/03/09 16:13:23 XIS3 



(note no timestamp) 



(but not CLEAR ! ) 
(XIS3 saved) 



(protects previous XIS3) 



(now XIS3 can be updated) 



(update XIS3) 
(new timestamp) 
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DISPLAY DEVICE PARAMETERS 

T^ P +-,xr^ H-iorVi^T- Hp^Hop nnramfitftrs maintain their settings, unless specifically altered, 
for the entire APL session. They are WIDTH and LINESo Default settings are assigned 
at the start of a session based on the declared terminal type (including batch). These 
parameters do not reside in the active workspace, and thus are not contained in saved 
workspaces. 



WIDTH COMMAND 



)WIDTH £<integer>} 30 <integer < 65535 



action: 



# WIDTH is set to the value supplied. 

# The previous value of WIDTH is reported. 



consequence: Until again changed later in the session, all displayed output will 

be formatted in lines not exceeding WIDTH characters in width. 
Data which otherwise would appear on the same line will be con- 
tinued on the following line or lines. The line continuation format 
for the declared display device will be used. 

default value: See appendix D for default values for specific terminals. 



LINES COMMAND 



)LINES {<integer>] 



^integer < 1+2*4 7 



action: 



# LINES is set to the value supplied. 

• The previous value of LINES is reported. 



19980800 B 



14-31 



consequence: 



note: 



If the setting of LINES is non-zero, output is displayed on the 
output device in "pages" LINES lines long. At the end of each 
"page ", the display will halt and request go-ahead according to 
the device type. This consists of a request for input with a 
'MORE? ? ' at the left margin. Any input other than '$A. ' will 
then cause the display to continue. The last such "page" does 
not request go-ahead, as the display is complete. Neither does 
"fill" to the end of the page occur. If the setting of LINES is 
zero, no paging occurs. 

The remainder of the display is aborted by signalling ATTENTION, 



default value: 



The default setting of lines will be equal to the line capacity of the 
display less 2 (to allow for the prompt line and input line). 

The most usual non-default setting of LINES is zero which causes 
continuous scrolling of output without halts for the entire display. 
Zero is the default setting for all hard copy terminals. 

See appendix D for default values. 



14-32 



19980800 B 



EXTERNAL FILE INTERFACE 

At the moment, only two commands are available to interface to files external to APL. 
One command performs input, and the other performs outputo 



INPUT COMMAND 

syntax: 
action: 



)INPUT < FILENAME> 

All input is subsequently taken from the named file. The file is 
assumed to be a standard ASCII file. When the end of the file is 
reacfleQ, input is a.gcu.11 a^>-cpi.cvi ±±^±±1. "^ ,v* ^^.x^i. 



OUTPUT COMMAND 

syntax: 
action: 



)OUTPUT < FILENAME > 

A log of the entire session is placed on the named file in standard 
ASCII format, in a form suitable for printing. 

Each OUTPUT command purges the previous contents of the named 
file. 

The log will be formatted according to the WIDTH and LINES 
values for the output device and cannot be altered. Responses 
to )WIDTH and )LINES in the log will however be those values in 
force at the time issued. 
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TERMINATING AN APL SESSION 

SYSTEM COMMAND 

syntax: )SYSTEM 

action: The session is terminated, the active workspace is destroyed, 

and the user is returned to the system from which APL was 
called. 



14-34 19980800 B 



ACCESS TO APL*STAR ON STAR OS 



1. Establish user identity by a LOGON line. 

2. Initiate execution of APL*STAR by entering the name of the file containing 
the APL interpreter,, The system responds with: 

APL*STAR VI. 1 

At this point the user is in direct communication with the APL*STAR system. 
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COMMUNICATING APL CHARACTERS B 



METHODS 



The APL characters are summarized in Table B-l. Communicating these characters 
between a terminal (or batch input ana output dev^c, a..u me Ax *.-&.«« «js — ^ 
achieved in one or more of the following ways: 

1. Terminal keys corresponding to APL characters communicate those characters 
when struck. 

2. Specific terminals may have a certain key defined as a substitute for a certain 
APL character and convey that character when depressed. Such particulars are 
listed under the appropriate section of supported terminals. 

3. On non-destructive display terminals (i. e. , hard copy or storage tube) which are 
equipped with a backspace key, certain APL characters may be communicated by 
overstriking (explained below). 

4. A scheme of three character mnemonics exists for conveying any desired APL 
character and can be used on any terminal or batch I/O device. 

Output displays will, for each required character, utilize one of the above methods, 
according to device capabilities, in the preferred order as listed. 

OVERSTRIKES 

On terminals with a non-destructive overstrike, such as hard copy or storage tube terminals, 
repositioning to the line position of a previously keyed character and keying a second non- 
blank key (called overstriking) creates a compositely formed display graphic. If this 
graphic is a reasonable facsimile oi the symbol for an APL character, that character is 
conveyed; otherwise the character is illegal, and is converted to the canonical 'bad- 
character. Note that underscored alphabetics and underscored A (delta) are equivalent 
symbols for lower case alphabetics and $ respectively and may be formed by overstriking. 
On terminals with a standard APL keyboard, all but a very few special characters can be 
conveyed by direct keying or overstriking. 
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Note that as a consequence of the Visual Fidelity criterion, the keying sequence used in 
forming overstrikes is immaterial. Also, repeated overstriking the same key in the same 
line positon still conveys the same character. Overstriking with the space bar does not 
change the character conveyed. 

MNEMONICS 

On terminals not equipped with a standard APL keyboard, and as an alternative for any 
type of terminal, desired APL characters can be conveyed by means of mnemonics. 

Mnemonics exist for the entire APL character set except for the following 46 characters 
which are standard on any terminal: 

A '" Z °'-- 9 ..() + - = */ and space 

Further, there are no mnemonics for backspace, return, or any other non-graphic 
characters. 

All mnemonics are formed by a three-character combination consisting of a dollar sign 
($) followed by two upper case alphabetic characters. The $ character acts as a flag 
character and conveys that it along with the following two characters are to be treated as 
a group which compositely represents a single APL character. The $ character is 
standard on all terminals except some of those with APL keyboards. An overstrike com- 
bination exists to convey the $ character in this case. If the $ character itself is desired 
as a literal character, the mnemonic for dollar sign can be used. 

Also, a dollar sign is considered literal if it is not followed by an upper case alphabetic 
(e.g., '$1.50'). 

The two upper case alphabetic characters following the $ character have been chosen by 
the following scheme to aid in remembering them: 

• Lower case Roman alphabetic characters are conveyed by the double appearance of 
the corresponding upper case character. 

. If the APL character is used only as a character and not as a primitive function 
designator the two characters are an abbreviation f or the 



imp *-\-p J-t-.*-i ,--_,— — T .1 



• If the APL character is used as a primitive function designator, but is a character 
which has a generally known name, the two characters are an abbreviation for the 
name of the symbol. 
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* If the APL character is used as a primitive function designator and is a character 

lUI' Wii-LCU I1U -J.cUi._e CAISISi Ul Wim-" J-0 -h-*- vv a.v_\_.-.jf iviiuvtii, -l-K l vv w i_nai <H_(,C1 o cU. C cl-J. 

abbreviation for the name of the primitive function. If the function is known by- 
more than one name, an abbreviation of the most frequently used name is chosen. 

9 For those APL primitives for which an alternate APL character exists, implicitly 
indicating 'first' for the indicated ordinal processing of the right argument, the two 
characters used are obtained from the two characters used in the mnemonic for the 
APL character which represents the standard form of the function call, replacing 
the second character by the next higher in the alphabet. 

For the convenience of users on terminals in which lower case is the normal alphabetic 
mode, lower case letters are accepted as equivalent to upper case in the mnemonic letter 
pair. 

x lie COIlipiGtc S6l Oi jnsrj-i uiidrcLui-cr muciTiuiuCa ±o uaicu ±n ±auic d^i, 

COMPATIBILITY 

It should be noted that, no matter how APL characters are communicated from whatever 
type of terminal, the APL system converts each APL character representation to a 
standard internal representation for processing. SAVE'd workspaces are also stored in 

this format. 

This means that workspaces created while on one type of terminal may subsequently be 
loaded while on a different terminal type. Compatibility of workspace contents is thus 
ensured for users of all terminal types. 



19980800 A B-3 



TABLE B-l. APL CHARACTER SET 



Graphic 


Mnemonic 


Meaning 


? 


$QU 


QUery 


bi 


$OM 


OMega 


e 


$EP 


EPsilon 


P 


$RO 


RhO 


~ 


$TL 


TiLde 


+ 


$TA 


TAke 


4- 


$DR 


DRop 


l 


$IO 


IOta 


O 


$CI 


Circle 


4> 


$RT 


RoTate 


e 
6? 


$RU 
$TP 


(reverse indexed 
rotate) 
TransPose • 


* 


-- 


asterisk 


9 


$LG 


LoG 


->■ 


$GO 


GOto 


■*- 


$IS 


IS 


a 


$AL 


ALpha 


r 


$MX 


MaX 


L 


$MN 


MiN 


- 


$UL 


UnderLine 


V 


$DL 


DeL 


V 


$LD 


Locked Del 


? 


$DG 


DownGrade 


A 


$DT 


DelTa 


5(A) 


$DU 

$UG 


Delta Underscored 
(lower case delta) 
UpGrade 



Graphic Mnemonic Meaning 



A 

thru 

Z 


-- 


(upper case 
alphabetics) 


a(4) 
thru 
z(Z) 


$AA 
thru 
$ZZ 


(lower case 
alphabetics) 



thru 


-- 


(numerics) 


9 







(space) 

"(") $DQ Double Quote 

~(~ t ") $NG NeG 

< $LT Less Than 

< $LE Less than or 

Equal 
EQual 

> $GE Greater than or 

Equal 

> $GT Greater Than 

* $NE Not Equal 
v $OR OR 

v $NR NoR 

a $AN ANd 

* $ND NanD 

minus 
+ -- plus 

r $DV DiVide 

1 |XD matrix Divide 

x $ML MuLtiply 
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TABLE B-l. APL CHARACTER SET (Cont'd) 



Graphic Mnemonic 
$NL 

• $QT 

: sex 

□ $QD 

a $qp 

( 

) 

[ $OB 

] $CB 



$ID 

$IN 

$IX 

SEP 

$UN 

$BV 

$RP 

$IB 

$MD 

$SC 

$CL 

$BS 

$BT 



Ki) 



Meaning 
NuLl 




Graphic 
# 


Miieiiiuiiiu 


A T ^ <^ v-i i v-i re 


$NM 


NuMber sign 


QuoTe 




'?($) 


$DO 


DOllar sign 


EXclamation mark 




r> 

,3 


$PC 


PerCent sign 


QuaD 




£ 


$AM 


Ampersand 


Quad -Prime 







$AT 


AT sign 


paren (left parenthesi 


s) 


{ 


$LB 


Left Brace 


close (right parenthe: 


sis) 


} 


$RB 


Right Brace 


Open Bracket (sub) 




< 


$CT 


CenT sign 


Close Bracket (bus) 




<> 


$DM 


DiaMond 






-\ 


$RK 


Right tacK 


ImbeD 




h 


$LK 


Left tacK 


INclusion 




\ 


$GV 


GraVe accent 


Inter seXion 




1 


$EV 


EValuate 


LamP 




* 


$FM 


ForMat 


UNion 




t 


$CN 


(reverse inde 
comma) 



$SM 



Base Value 

Representation 

I-Beam 

MoDulus 

SemiColon 

CoLon 

BackSlash 

(reverse indexed 
backslash) 
comma 

dot 

slash 

„_Xxever^.e-.iiLdexgd 
slash) 



Special Characters: 

(0) $G. 

$BC 



$A. 
$CO 



(quad -prime 
escape) 



(canonical 
bad character) 



(error marker) 
(output escape) 



(continuation 
character) 
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• 



• 



• 



• 



NUMERIC REPRESENTATION ON STAR COMPUTERS 



An exact representation for zero exists. 

The sum of any selection from any 47 consecutive terms of the power series of 2 



z*( zisotz ... "1 1 



in which at least one term is greater than or equal to 2*~28626 can be re- 
presented exactly. 

The negation of any such number except 2*~28626 can be represented exactly. 
In addition the negation of 2*28718 can be represented exactly. 

Any number outside this range cannot be represented and is not in the domain of 
definition or result range of any numeric APL function. 

Any number within the range 

(-( (2*"28626)+2*"28672) ),(2#~28626) 
is approximated by the representation for zero by all numeric APL functions. 

All other real numbers will be represented by the exact representation of the 
approximation to the desired value obtained by summing the 47 most significant 
terms of the value expressed as a power series of 2. 
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TERMINAL CAPABILITIES OF APL*STAR 



DISPLAY-EDIT STATION 

# WIDTH 63 

9 LINES 15 

e Local line editing facilities: 
backspace 
forward space 
clear line 

destructive over strike 
deletion of everything above and to right of cursor. 

# Quad prime input does not cause input to be formed by the catenation of the 
previous quad prime output and the input typed by the user. (Device does 
not support output followed by input on the same line. ) 

m Signalling ATTENTION 

input - not needed (see local line editing facilities). 



output /execution - send(Fj) 5 1 

Note: The actual control character used is installation 
dependent, 

in response to MORE?? message - send $A. 
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CARD READER FILE (accessed through INPUT command) 

• Quad prime input does not cause input to be formed by the catenation of the pre- 
vious quad prime output and the input typed by the user. (Device is not output 
device. ) 

• Local line editing facilities: 

APL does not support use of ESC control character to replace three 
or more contiguous blank characters. 

• No overstrike capability. 

• Signalling ATTENTION not possible. 

PRINTER FILE (accessed through OUTPUT command) 

• WIDTH 135 

• LINES 

• No overstrike capability. 
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INDEX 



Aborting execution and output 11-8 

Absolute FUZZ 5-11 

ABSOLUTE VALUE 7-5 

Active function 12-5 

Active workspace 14-2 

ADDITION 7-8 

AND 7-17 

APL - the language 1-1 

APL*STAR system 1-2 

Arccos 7-14 

Arccosh 7-14 

Arcsinh 7-14 

Arctan 7-14 

Arctanh 7-14 

Arguments 1-1 

Arrays 2-1 

BASE VALUE 9-10 

Body of function definition 12-1 

BOOLEAN FUNCTIONS 7-17 

Boolean numbers 5-4 

BRANCH 

monadic 12-3 

niladic 12-3 

Canonical Ravel 2-1 

Canonical form for expressions 10-6 

Canonical bad character B-l 

CATENATE 6-11 

CEILING 7-5 

Character set B-4 

Characteristic Data Type 2-2 

CIRCLE 

dyadic 7-14 

monadic: PI TIMES 7-5 
—CLEAR command- 43-3 



CLEAR WS 13-19 
COLON (use with labels) 12-4 
Combination 7-8 
Comments 11-10 
Composite data displays 4-6 
Composite functions 8-1 
COMPRESS 6-18 
Conformability 

singular 5-4 

dual 5-4 

overriding rules 5-5 
Coordinates 2-1 
COPY Command 14-26 
Cosh 7-14 
Cosine 7-14 

Data 2-1 

Data types 2-2 

DEAL: dyadic QUERY 9-5 

DEPTH ERROR 10-4 

Decimal form 4-2 

DEFINE command 13-10 

Defined (by user) functions 12-1 

DEFN ERROR 13-11 . 

Diagonal 6-26 

DIGITS 4-2 

Displaying 

composite data 4-7 

data 4-1 

expressions 10-6 

numeric data 4-4 
DISPLAY command 13-11 
DIVIDE 7-3, 7-9 
Domain (def'n) 5-2 
DOMAIN ERROR - 10 = 2 
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DROP 6-16 

DROP command 13-24 

Dyadic (def'n) 5-2 

Element of an array 2-1 
Empty (def'n) 2-2 
Entering input 11-9 
Environment of an active function 

global 12-5 

local 12-5 
EPSILON (dyadic): MEMBERSHIP 9-4 
EQUAL 7-15 
ERASE command 13-9 
Error detection sequence 10-2 
Error Recovery 10-5 
EXPAND 6-20 
EXPONENTIAL 7-3 
Exponential form 4-3 

EXPONENTIATION (dyadic POWER) 7-11 
Expressions 

conversion to internal form 10-1 

displaying 10-6 

error detection sequence 10-2 

input format 10-1 

literal 3-1 

order of evaluation of 10-2 

use of parentheses in 10-1 

use of spaces in 10-1 
EVALUATE 9-12 

FACTORIAL 7-6 
Fill element 6-1 
FLOOR 7-4 
FNS command 13-5 
FORMAT 9-18 

T7 , r>T»irv-t «-i tf i Y\rf 

numeric elements 4-2 
numeric data 4-4 



Function 

body 12-1 

call 12-2 

definition 12-1 

execution 12-2 

header 12-1 
nested calls 12-6 
primitive 5-1 
user-defined 12-1 
Function Editor 13-1 

Display Directives 13-3 
Editing Directives 13-5 
Invoking the 13-1 
Summary 13-7 
Terminating the 13-6 

FUZZ 

relative, with relationals 5-9 

absolute 5-11 
FUZZ command 13-8 

Gamma function 7-6 
Global environment 12-6 
Global object 12-6 
Global variable 12-6 
GRADE DOWN 9-7 
GRADE UP 9-6 
GREATER THAN 7-16 
GREATER THAN OR EQUAL 7-16 

Groups 

GROUP Command 14-6 
Group Definition 14-6 
Altering 14-6 
Displaying 14-7 
GRP Command 14-6 
Rpfprpnrincr Hrnnns 14-fi 
GRPS Command 14-5 
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I-BEAM (Dyadic) 9-20 
I-BEAM (MONADIC) 9-19 
Identifiers, rules for forming 3-3 
IDENTITY 7 = 2 
Identity element 8-5 
IMBED 9-15 
Immediate execution 11-1 
INCORRECT command 13-1 
INDEX ERROR 10-2 
INDEX OF: dyadic IOTA 9-2 
Index list 6-5 
Indexed functions 5-7 
INDEXED SPECIFICATION 6-8 
INDEXING 6-5 
INNER PRODUCT 8-8 
INPUT command 13-28 
INPUT submission procedure 11-9 
Integer domain 5-11 
INTERVAL: monadic IOTA 9-1 
* IOTA (dyadic): INDEX OF 9-2 
IOTA (monadic): INTERVAL 9-1 

Labels 12-4 

Laminate 6-13 

Least Squares Fit 9-28 

Length 2-1 

LENGTH ERROR 10-2 

LESS THAN 7-16 

LESS THAN OR EQUAL 7-16 

Linear Equations 9-24 

Linear Parametric Equations 9-27 

LINES command 13-26 

LIST data 2-2, 6-6, 9-15 

LOAD command 13-22 

LOGARITHM 

dyadic 7-12 

natural (monadic) 7-4 

Masking 12-5 
-Matrix 2-2 



MATRIX DIVISION 9-22 

MATRIX INVERSE 9-23 

MAXIMUM 7-13 

MEMBERSHIP: dyadic EPSILON 9-4 

MINIMUM 7-13 

Monadic (def'n) 5-2 

Mnemonics for APL characters B-2, 4, 5 

MULTIPLY 7-9 

NAND 7-17 

Natural LOGARITHM 7-4 

NEGATION 702 

NEGATIVE SYMBOL 3-2 

Nested function calls 12-6 

Niladic BRANCH 12-3 

Niladic functions 12-1 

NONCE ERROR 10-4 

NOR 7-17 

NOT (monadic TILDE) 7-7 

NOT EQUAL 7-16 

NOT SAVED - THIS WS IS . . . 13-20 

NOTATION 

APL syntax 5-1 

special 1-3 
Numeric 

data 2-1 

data formatting 4-4 

element formatting 4-2 

representation on STAR computers C-l 

OR 7-17 

Ordinals 5-3 

ORIGIN command 13-16 

Origin 5-7 

Origin dependence 5-7 

OUTER PRODUCT 8-2 

Output - see Displaying Data 

OUTPUT command 13-28 

Over strikes B-l 
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Parentheses in expressions 10-1 
Pendant function 12-6 
PI TIMES (monadic CIRCLE) 7-5 
POWER (dyadic): EXPONENTIATION 
PCOPY Command 14-28 

QUAD 

in expressions 4-1 

input 11-2 
QUAD -PRIME 

escape 11-5 

input 11-5 
QUAD-PRIME PROMPT 11-7 
QUERY 

(dyadic): DEAL 9-5 

(monadic): ROLL 7-6 

Range (def'n) 5-2 
Rank 

def'n 2-1 

termiology 2-2 
RANK ERROR 10-2 
RAVEL 2-1; 6-4 
RECIPROCAL 7-3 
Recursive function calls 12-7 
REDUCTION 8-4 
REF ERROR 10-4 
REPRESENTATION 9-8 
RELATIONAL functions 7-15, 16 
RESHAPE: dyadic RHO 6-2 
RESIDUE 7-10 

Result variable 12-1 
REVERSAL 6-22 
Reverse Indexing 5-8 
ROLL: monadic QUERY 7-6 
ROTATE 6-23 

SAVE command 13-20 
Saved workspaces 13-18 



Scalar 

def'n 2-2 

extension 5-5 
7-11 functions 7-1 

SEED command 13-7 

Seed 5-13 

Selection function (def'n) 6-1 

SEMICOLON 

in composite displays 4-6 

in index lists 6-5 

in explicit local lists 12-1 
Sequence of execution 10-2 
SHAPE: monadic RHO 2-1; 6-3 
Significant digits 4-2 
SIGNUM 7-2 
Sine 7-14 
Sinn 7-14 
SI 13-13 
SI DAMAGE 13-9 
SIV 13-15 
SIZE command 13-8 
Spaces in expressions 10-1 
Special notation 1-3 
SPECIFICATION 

def'n 3-3 

INDEXED 6-8 
State Indicator 13-13 
STOP command 13-16 
Stop list 13-16 
SUBTRACTION 7-8 
Suspended function 12-7 
SYMBOL TABLE FULL 10-4 
Syntax 

primitive function 5-2 

system command 13-1 
SYNTAX ERROR 10-2 
SYSTEM command 13-29 
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System Commands 
general 13-1 

\/~*T T7< ATD 1 Q_Q 

)DEFINE 13-10 

)DIGITS 13-6 

)DISPLAY 13-11 

)DROP 13-24 

^ERASE 13-9 

)FUZZ 13-8 

)FNS 13-5 

)INPUT 13-28 

)LINES 13-26 

)LOAD 13-22 

)VARS 13-5 

)OBS 13-5 

)ORIGIN 13-6 

)OUTPUT 13-28 

)SAVE 13-20 

)SEED 13-7 

)SI 13-13 

)SIV 13-15 

)SIZE 13-8 

)STOP 13-16 

)SYSTEM 13-29 

)VARS 13-4 

) WIDTH 13-26 

)WSID 13-25 
System (APL*STAR) 1-2 
System information: I-BEAM 9-19, 20 



TAKE 6-14 

Tangent 7-14 

Tanh 7-14 

Terminal access to APL*STAR system 
on STAR OS A-l 

Terminating an APL session 13-29 

TILDE (monadic): NOT 7-7 

TRANSPOSE 

dyadic 6-25 

monadic 6-25 

Value 2-2 

VALUE ERROR 10-2 

Variable 

assigning new value to 3-4 

defining 3-3 

referencing 3-3 
VARS command 13-4 
Vector 2-2 
Visual fidelity 11-8 

WIDTH command 13-26 
Workspace 

active 13-2 

identification 13-18 
WS FULL 10-4 
WSID command 13-25 
WS LOAD only 13-20 
WS LOCKED 13-22 
WS NOT LOCKED 13-22 
WS NOT FOUND 13-22 
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